Skip to content

glint docs update #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ZFordDev merged 1 commit into from
Aug 20, 2026
Merged

glint docs update #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Changelog

All notable user-facing changes to Glint are recorded here.

## v1.0.0 (2026-08-20)

Glint's first stable release turns the original Windows prototype into a tested, cross-platform desktop monitor.

### Added

- Cross-platform application and system tray support for Windows, macOS, and Linux
- CPU, RAM, disk, GPU usage, GPU temperature, and live network widgets
- Portable sensor collection through `psutil`, optional Windows WMI, and `nvidia-smi`
- Independent Settings window with live refresh interval, opacity, and theme controls
- Default and Midnight themes
- Versioned JSON preferences, persistent HUD position, and editable widget layouts
- Native autostart entries for Windows, macOS, and freedesktop Linux desktops
- Tests and formatting checks across all three supported operating systems
- Automated native GitHub Release archives and SHA-256 checksums

### Fixed

- Restored HUD dragging, including compositor-assisted movement on Wayland
- Prevented Settings from behaving like a panel attached to the frameless HUD
- Made unavailable hardware readings fail gracefully instead of blocking startup
- Corrected Python packaging, console entry points, dependencies, and macOS application bundles

### Changed

- Consolidated project dependencies in `pyproject.toml`
- Replaced the old Windows-only implementation with shared platform-aware modules
- Adopted GitHub Releases as the only official distribution channel

[v1.0.0 release](https://github.com/ZFordDev/Glint/releases/tag/v1.0.0)
78 changes: 78 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Contributing to Glint

Thank you for helping improve Glint. Bug reports, platform testing, documentation, design feedback, and focused code contributions are all welcome.

Please report security vulnerabilities through the private process in [SECURITY.md](SECURITY.md). Glint also follows the broader [ZFordDev project standards](https://github.com/ZFordDev/ZFordDev/blob/main/STANDARDS.md).

## Before you begin

- Search the [issue tracker](https://github.com/ZFordDev/Glint/issues) for an existing report.
- Open an issue before starting a substantial feature or architectural change.
- Keep changes aligned with Glint's lightweight, local-only system-monitoring role.
- Never include private machine information, usernames, hostnames, or unrelated logs in a report.

## Development setup

Glint requires Python 3.10 or later and a graphical desktop session.

```bash
git clone https://github.com/YOUR-USERNAME/Glint.git
cd Glint
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"
python main.py
```

Create a focused branch from the latest `main` branch:

```bash
git switch -c fix/short-description
```

## Making changes

- Keep pull requests limited to one logical change.
- Preserve graceful fallbacks when a metric, platform feature, or system tray is unavailable.
- Keep platform-specific imports and behavior isolated behind runtime checks.
- Avoid heavy dependencies unless the benefit clearly justifies the download and maintenance cost.
- Keep drawing logic in the UI layer and sensor collection in `src/core/`.
- Update the README and DocsHub pages when behavior, packaging, or platform support changes.
- Do not turn sensor readings into persistent history, telemetry, or network traffic without prior discussion.

## Testing

Run the automated checks before opening a pull request:

```bash
ruff format --check .
ruff check .
python -m pytest
```

Also launch Glint and manually exercise the changed workflow. Platform-sensitive changes should be tested on Windows, macOS, and Linux when possible. If you cannot test a platform, say so clearly in the pull request.

For UI changes, check HUD dragging, the independent Settings window, tray restoration, opacity, both built-in themes, and behavior when optional sensor values are unavailable. For release changes, use the GitHub Release workflow's non-publishing rehearsal mode or run the equivalent release-script validation locally.

## Pull requests

1. Push your branch and open a pull request against `main`.
2. Explain what changed, why it changed, and how it was tested.
3. Link related issues with a keyword such as `Fixes #123` when appropriate.
4. Include screenshots for visible HUD or Settings changes.
5. Keep unrelated formatting and refactoring out of the pull request.

Clear, present-tense commit messages are appreciated.

## Good bug reports

Please include:

- Glint version and whether it came from a release archive or source
- Operating system, version, architecture, desktop environment, and display server where relevant
- CPU/GPU model and driver when the problem involves sensors
- Clear reproduction steps and expected versus actual behavior
- Relevant logs or screenshots with personal information removed

Thank you for contributing to Glint.
34 changes: 34 additions & 0 deletions PRIVACY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Glint Privacy Statement

**Effective date:** v1.0.0 (August 2026)

## Local-only monitoring

Glint is a local desktop system monitor. It reads operating-system and hardware metrics to render the HUD on your device. Glint does not upload, synchronise, sell, or otherwise transmit those readings.

## What Glint reads

- CPU and memory utilisation
- Mounted-disk labels and utilisation
- Network byte counters used to calculate current upload and download rates
- Temperature and GPU utilisation when exposed by the operating system, driver, WMI, or `nvidia-smi`

These readings are held only long enough to update the display. Glint does not maintain a monitoring history or write sensor values to disk.

## What Glint stores

Glint stores a small local configuration containing the refresh interval, opacity, selected theme, layout name, and HUD position. It also stores JSON layout files describing the HUD size and widget placement. These files remain in the operating system's application configuration directory.

Glint has:

- no accounts or sign-in;
- no analytics or telemetry;
- no advertising or tracking;
- no cloud storage or synchronisation; and
- no built-in network update checker.

Updates are downloaded manually from [GitHub Releases](https://github.com/ZFordDev/Glint/releases). Visiting GitHub is governed by GitHub's own privacy terms; the Glint application itself does not contact GitHub.

## Questions

For privacy questions, open an issue at [github.com/ZFordDev/Glint/issues](https://github.com/ZFordDev/Glint/issues) or inspect the source code in this repository.
131 changes: 78 additions & 53 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,80 @@
<div align="center">

<img src="assets/icon.svg" width="112" alt="Glint icon">

# Glint

Glint is a lightweight, painter-rendered desktop system monitor for Windows, macOS, and Linux. It displays CPU, memory, disk, GPU, temperature, and live network metrics without a browser or Electron runtime.
### A lightweight system-monitor HUD for Windows, macOS, and Linux

[Documentation](https://docs.zford.dev/zforddev/glint/) · [Downloads](https://github.com/ZFordDev/Glint/releases/latest) · [Report a bug](https://github.com/ZFordDev/Glint/issues/new)

[![Release](https://img.shields.io/github/v/release/ZFordDev/Glint?label=release)](https://github.com/ZFordDev/Glint/releases/latest)
[![Checks](https://github.com/ZFordDev/Glint/actions/workflows/python-app.yml/badge.svg)](https://github.com/ZFordDev/Glint/actions/workflows/python-app.yml)
![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-6b8afd)
[![License](https://img.shields.io/github/license/ZFordDev/Glint)](LICENSE)

</div>

Glint keeps essential system information visible in a compact, translucent desktop HUD. It is built with PyQt 6 and drawn directly with `QPainter`, keeping the application small and avoiding a browser or Electron runtime.

CPU, memory, disk, GPU, temperature, and network readings are collected locally. Hardware-specific readings degrade gracefully: when a sensor is not exposed by the operating system or driver, Glint shows it as unavailable and continues running.

## Highlights

- Native PyQt 6 HUD and system tray
- Portable CPU, RAM, disk, temperature, and network sensors through `psutil`
- NVIDIA GPU usage and temperature through `nvidia-smi`, with graceful fallback on other hardware
- JSON-backed settings and user-defined widget layouts
- Built-in themes and serializable painter-rendered widgets
- Native, frameless PyQt 6 HUD with persistent positioning
- CPU, RAM, disk, GPU, temperature, upload, and download widgets
- Independent Settings window with live refresh-rate, opacity, and theme controls
- Default and Midnight themes with JSON-backed custom layouts
- System tray controls for showing Glint, opening Settings, autostart, and exit
- Native autostart entries for Windows, macOS, and freedesktop Linux desktops
- Standalone GitHub Release archives that do not require Python

## Download

Download the archive for your system from the [latest GitHub Release](https://github.com/ZFordDev/Glint/releases/latest):

Unavailable hardware metrics display as “Unavailable”; they do not prevent Glint from starting.
| Platform | Release asset |
| --- | --- |
| Windows x86-64 | `glint-windows-x86_64.zip` |
| macOS Apple silicon | `glint-macos-arm64.zip` |
| macOS Intel | `glint-macos-x86_64.zip` |
| Linux x86-64 | `glint-linux-x86_64.tar.gz` |

## Requirements
Extract the archive and launch `Glint` (`Glint.exe` on Windows). Release checksums are published in `SHA256SUMS`.

> [!NOTE]
> Glint's standalone archives are currently unsigned. Windows SmartScreen or macOS Gatekeeper may ask you to confirm that you trust the download. Official builds are published only through this repository's GitHub Releases.

## Use Glint

| Action | Result |
| --- | --- |
| Left-click and drag the HUD | Move it and remember the new position |
| Right-click the HUD | Open Settings or exit Glint |
| Double-click the tray icon | Show and raise the HUD |
| Open the tray menu | Show Glint, open Settings, manage autostart, or exit |

Settings and layouts are stored in the operating system's application configuration directory. The generated `default_layout.json` can be edited to change the HUD size, widget order, positions, and disk selection. See the [Glint documentation](https://docs.zford.dev/zforddev/glint/) for examples and platform notes.

## Sensor support

| Metric | Windows | macOS | Linux |
| --- | --- | --- | --- |
| CPU, RAM, disk, network | `psutil` | `psutil` | `psutil` |
| CPU temperature | WMI when exposed | `psutil` when exposed | hwmon through `psutil` |
| NVIDIA GPU usage and temperature | `nvidia-smi` | `nvidia-smi` when supported | `nvidia-smi` |
| AMD/Intel GPU usage | Windows performance counters | Unavailable fallback | Unavailable fallback |
| Other GPU temperatures | Platform sensor when exposed | Platform sensor when exposed | hwmon when exposed |

- Python 3.10 or later
- Windows 10+, a current macOS release, or a Linux desktop with a system tray
- A graphical desktop session
Temperature and GPU availability varies by hardware, driver, permissions, and operating system. Wayland compositors may also prevent applications from forcing the HUD below other windows; Glint remains frameless and usable when that hint is ignored.

Linux packages may require Qt system libraries supplied by the distribution. Wayland desktop-shell rules can prevent applications from forcing a window below every other window; the HUD remains frameless and behaves normally in that case.
## Run from source

## Install and run
Glint requires Python 3.10 or later and a graphical desktop session.

```bash
git clone https://github.com/ZFordDev/Glint.git
cd Glint
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
Expand All @@ -35,57 +86,31 @@ For development:

```bash
python -m pip install -e ".[dev]"
python -m pytest
ruff format --check .
ruff check .
python -m pytest
python main.py
```

## Controls
The test workflow runs on Windows, macOS, and Linux for every pull request and push to `main`.

- Left-click and drag moves the HUD.
- Right-click opens Settings or exits.
- Double-clicking the tray icon restores the HUD.
- The tray menu controls autostart.
## Data and privacy

Settings and layouts use the operating system's application configuration directory. A generated `default_layout.json` can contain multiple disk widgets; set each widget's `disk` field to its device label.
Glint has no accounts, analytics, telemetry, advertising, or cloud service. System readings are displayed locally and are not written to history or transmitted. Only preferences, the HUD position, and layout files are saved on the device. Read the full [privacy statement](PRIVACY.md).

## Sensor support
## Project status

| Metric | Windows | macOS | Linux |
| --- | --- | --- | --- |
| CPU, RAM, disk, network | `psutil` | `psutil` | `psutil` |
| CPU temperature | WMI when exposed | `psutil` when exposed | hwmon through `psutil` |
| GPU usage | `nvidia-smi`, then WMI for AMD/Intel | `nvidia-smi` when supported | `nvidia-smi` |
| Other GPU temperature | unavailable fallback | platform sensor when exposed | hwmon when exposed |
Glint v1.0.0 is the first stable, cross-platform release. Distribution is intentionally minimal and GitHub-exclusive: there are no Microsoft Store, Mac App Store, Snap Store, or other store packages, and the legacy `glasshub-updater` prototype is not a supported update path.

Hardware and driver vendors expose sensors inconsistently, so temperature and GPU metrics are optional by design.
Releases are built by GitHub Actions from matching `v*` tags. The workflow verifies formatting, lint, tests, and version consistency before creating native archives and SHA-256 checksums. Maintainer details are documented in [architecture and maintenance notes](https://docs.zford.dev/zforddev/glint/maintenance/).

## Project layout
## Contributing and support

```text
src/
core/ sensors, settings, themes
ui/ HUD, tray, settings, layouts
widgets/ independent painter widgets
app.py application entry point
tests/ core behavior tests
```
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before preparing a change.
- Use the [issue tracker](https://github.com/ZFordDev/Glint/issues) for reproducible bugs and focused feature requests.
- Report vulnerabilities privately using [SECURITY.md](SECURITY.md).
- Review release history in [CHANGELOG.md](CHANGELOG.md).

## License

MIT

## Releases

Glint is distributed exclusively through GitHub Releases as minimal standalone archives—there are no Microsoft Store, Snap Store, or other store packages.

The archives are currently unsigned. Windows SmartScreen and macOS Gatekeeper may therefore ask users to confirm that they trust the download. Code signing can be added later without changing the GitHub-only distribution model.

Maintainers publish a release by updating `project.version` in `pyproject.toml`, merging the tested change to `main`, and pushing a matching tag such as `v1.0.0`. GitHub Actions then:

1. verifies formatting, lint, tests, and the tag/version match;
2. builds native Windows, macOS, and Linux bundles with PyInstaller;
3. creates SHA-256 checksums; and
4. publishes the archives and generated notes to the tagged GitHub Release.

The workflow can also be started manually in rehearsal mode, which validates and builds without publishing. Enabling its `publish` input requires an existing matching tag and creates the release after all builds succeed.
Glint is open-source software released under the [MIT License](LICENSE).
34 changes: 34 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Security Policy

Glint welcomes responsible reports that help keep its users and systems safe.

## Supported versions

Security fixes target the latest stable release and the current development branch. Older releases, forks, modified builds, and unofficial distributions may not receive fixes. Users should update to the latest stable GitHub Release when a security update is published.

## Report a vulnerability privately

Use [GitHub's private vulnerability reporting](https://github.com/ZFordDev/Glint/security/advisories/new) whenever possible.

If that form is unavailable, email [zforddev@gmail.com](mailto:zforddev@gmail.com) with `Glint security report` in the subject line.

Do not open a public issue, discussion, or pull request for an unpatched vulnerability. Include the affected version and platform, potential impact, reproduction steps or a minimal proof of concept, and any useful logs with personal information removed.

Reports made in good faith should avoid accessing data that is not yours, disrupting other systems, or causing harm. The maintainer will review the report, attempt to reproduce it, prepare a fix or mitigation when appropriate, and coordinate disclosure through the original private channel.

## Scope

This policy covers Glint's source code and official GitHub Release archives, including sensor collection, configuration and layout file handling, autostart integration, packaging, and bundled dependencies.

The following are generally outside scope unless they create a vulnerability in an official release:

- Unsupported versions, forks, and modified or unofficial builds
- Vulnerabilities that require an already-compromised operating system
- Hardware or driver behavior that only makes a metric unavailable or inaccurate
- Reports that identify an outdated dependency without demonstrating relevant impact

## Security characteristics

Glint reads local operating-system metrics and may call locally installed facilities such as WMI or `nvidia-smi`. It does not require administrator privileges, expose a network service, collect telemetry, or transmit sensor readings. Preferences and layouts are stored locally in the platform application configuration directory.

Official archives are currently unsigned. Verify downloads against the `SHA256SUMS` file attached to the same GitHub Release and obtain releases only from `github.com/ZFordDev/Glint`.
Loading