Files
JD DavisandCopilot e9301f34c1 feat(tray): opt-in system tray icon with savings counter, dashboard and update alert (#4726)
## Description

Adds an **opt-in system tray icon** for Headroom while it runs (Windows
first; macOS/Linux planned). The icon is the Headroom logomark and its
right-click menu shows a compact savings counter (tokens and estimated $
saved), opens the dashboard, alerts when an update is available, and
lets you quit.

Closes #

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- New `headroom/tray/` package: `core.py` (GUI-free stats
polling/formatting), `icon.py` (logomark drawn with Pillow, no binary
assets in the wheel), `app.py` (pystray app), `launcher.py` (spawns the
tray as a child of the proxy).
- `headroom proxy --tray` starts the tray with the proxy; `headroom tray
--port N` attaches to a running proxy.
- Menu: live `▼ tokens · ~$ saved` counter (from `/stats` →
`persistent_savings.lifetime`, polled every 5s), Open Dashboard, "Update
available" (only when newer; reuses `headroom.update_check`, honours
`HEADROOM_UPDATE_CHECK=off`; one-time notification), Quit.
- Icon states: normal, orange dot when an update exists, grey when the
proxy is offline.
- New optional extra `headroom-ai[tray]` (`pystray`, `pillow`).
Unsupported platform / missing extra: `--tray` prints why and the proxy
starts normally.
- Docs: `docs/content/docs/system-tray.mdx` + nav entry; screenshots in
`docs/public/assets/tray/`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
> python -m ruff check headroom\tray headroom\cli tests\test_tray_core.py
All checks passed!
> python -m mypy headroom\tray headroom\cli\tray.py
Success: no issues found in 7 source files
> python -m pytest tests\test_tray_core.py tests\cli tests\test_offline_egress_chokepoint.py tests\test_proxy\test_settings_store.py -q
293 passed, 2 skipped
```

(Scoped runs; I did not run the full suite or `mypy headroom` over the
whole package.)

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.13, 3840x2160 display, `pystray`
+ `pillow` 12.3.0, branch based on `upstream/main` @ 1da8930ab.
- Exact command / steps: run the 4 steps below.
1. `HEADROOM_UPDATE_CHECK=off`, then `python -m headroom.cli proxy
--tray --port 8799`
2. Confirmed `GET /health` → 200 and a `python -m headroom.tray --host
127.0.0.1 --port 8799 --owns-proxy` child process.
3. Opened the taskbar overflow, right-clicked the Headroom icon,
captured the menu (below).
  4. Clicked **Quit Headroom**.
- Observed result: icon appeared with the logomark; menu showed `▼ 256M
tokens · ~$765.96 saved` (my real lifetime savings store), **Open
Dashboard**, **Quit Headroom**. After Quit, `/health` no longer
responded (proxy shut down gracefully).
- Not tested: the real update toast and "Update available" menu item
(covered only by a unit test of `available_update()` and a rendered
icon); clicking Open Dashboard / double-click default action; macOS and
Linux (intentionally unsupported for now); HiDPI/light-theme variations;
`headroom tray` standalone Exit in the UI.

## Runtime Rollout Safety

- Rollout-managed feature(s): None (not rollout-channel gated).
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. Off by default; only active with
`--tray`.
- Kill switch / disable path: omit `--tray` (or pass `--no-tray`).
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: revert this PR; the new extra and command are additive.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes (only
`tests/test_tray_core.py` and `tests/cli` were run)
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

**Tray icon** (left: real icon in the Windows taskbar overflow, zoomed;
then rendered states: live, update available, proxy offline)

![Tray icon
states](https://raw.githubusercontent.com/JerrettDavis/headroom/3e824653772642c95fded190b454fff82f2ce86a/docs/public/assets/tray/tray-icon.png)

**Right-click menu** (real capture)

![Tray right-click
menu](https://raw.githubusercontent.com/JerrettDavis/headroom/3e824653772642c95fded190b454fff82f2ce86a/docs/public/assets/tray/tray-menu.png)

**How to use**

```bash
pip install "headroom-ai[tray]"
headroom proxy --tray        
headroom tray --port 8787    # attach to an already-running proxy
```

Windows hides new tray icons in the `^` overflow next to the clock; drag
the icon onto the taskbar to pin it, then right-click. Full guide:
`docs/content/docs/system-tray.mdx`.

## Feature spec

- **API surface**: `headroom proxy --tray/--no-tray`, `headroom tray
--port N`, extra `headroom-ai[tray]`. No change to existing behavior
when the flag is absent.
- **User stories**: Given the proxy runs with `--tray`, when I
right-click the icon, then I see tokens/$ saved, Open Dashboard and
Quit. Edge: given the proxy is down, the icon turns grey and the tooltip
says offline.
- **Failure modes / recovery**: unsupported platform or missing extra
prints a reason and the proxy starts normally; the tray child exits when
the proxy dies (stdin EOF); a stats fetch failure shows the offline
state and retries every 5s. Quit sends SIGINT for graceful shutdown
without a force-exit deadline.
- **Security**: tray only polls the local proxy `/stats`; no network
calls of its own (update info read from the existing cache; honours
`HEADROOM_UPDATE_CHECK=off`); child is spawned with a fixed argv.

## Dependency justification

- **Why**: `pystray` is the standard cross-platform tray library
(Win/macOS/Linux); `pillow` is required by it for icons and lets us draw
the logomark with no binary assets. No existing dep provides a tray.
- **Maintainers**: pystray (moses-palmer), BSD/LGPL, stable ~0.19.5
releases; Pillow (python-pillow org), very active, frequent security
releases.
- **Install surface**: optional extra only (not default). pystray pulls
`six`, plus pywin32-free ctypes on Windows; Pillow ships prebuilt
wheels. No install-time network access.
- **Why these versions**: `pystray>=0.19.5` is the current release
(required new functionality); `pillow>=12.3.0` matches the repo pin
level already used elsewhere to avoid known CVEs.

## Additional Notes

- The menu screenshot shows my real local savings numbers.
- The Quit item stops the proxy only when the tray was started via
`headroom proxy --tray`; the standalone `headroom tray` shows "Exit" and
only closes the tray.
- Follow-ups: macOS/Linux backends (pystray needs the main thread on
macOS, hence the child-process design).

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-16 19:40:55 -06:00
..