Extension for Windows

CONTRIBUTING.md

@@ -46,15 +46,27 @@ For the full macOS experience, run the installer from your checkout:
 ./scripts/install
 ```
 
-This starts the local server and menu bar companion. Open
+On Windows, install with the per-user PowerShell workflow:
+
+```powershell
+pwsh -NoProfile -File .\scripts\install-windows.ps1
+```
+
+This stages the browser dashboard under `%LOCALAPPDATA%\Token Meter\runtime`
+and registers automatic startup for the server and Windows system-tray widget.
+The AppKit menu-bar companion is macOS-only; the Windows companion uses the
+built-in PowerShell and WinForms runtime.
+
+The macOS installer starts the local server and menu bar companion. Open
 [http://localhost:8722](http://localhost:8722) and check its health with:
 
 ```bash
 curl http://127.0.0.1:8722/health
 ```
 
 Rerun `./scripts/install` after source changes when you want to test the staged
-runtime. For dashboard-only development, when port 8722 is free, run:
+runtime; on Windows, rerun `install-windows.ps1`. For dashboard-only
+development, when port 8722 is free, run:
 
 ```bash
 python3 meter.py
@@ -104,16 +116,29 @@ node -e "const fs=require('fs'); const html=fs.readFileSync('page.html','utf8');
 git diff --check
 ```
 
+On Windows, run the Python commands with the installed Python executable, parse
+the PowerShell scripts, and exercise the Windows installer:
+
+```powershell
+python -m py_compile meter.py token_meter_mcp.py
+python -m unittest discover -s tests -v
+node -e "const fs=require('fs'); const html=fs.readFileSync('page.html','utf8'); const m=html.match(/<script>([\s\S]*)<\/script>/); new Function(m[1]); console.log('js ok')"
+$files = 'scripts/install-windows.ps1','scripts/start-token-meter.ps1','scripts/run-tray.ps1','scripts/uninstall-windows.ps1','scripts/update-windows.ps1'
+$files | ForEach-Object { $tokens=$null; $errors=$null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $_),[ref]$tokens,[ref]$errors) | Out-Null; if ($errors) { throw $errors } }
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-tray.ps1 -SmokeTest
+pwsh -NoProfile -File .\scripts\install-windows.ps1
+```
+
 For menu bar changes, also run:
 
 ```bash
 swiftc menubar/TokenMeterMenuBar.swift -o /private/tmp/token-meter-menubar
 TOKEN_METER_MENUBAR_SMOKE=1 /private/tmp/token-meter-menubar
 ```
 
-For visible dashboard or menu bar changes, test the behavior in the running app
-and include a screenshot. If you cannot run a check—for example, because the
-Swift toolchain is unavailable—say so in the pull request.
+For visible dashboard, menu bar, or tray changes, test the behavior in the
+running app and include a screenshot. If you cannot run a check—for example,
+because the Swift toolchain is unavailable—say so in the pull request.
 
 ## Pull request checklist
 

README.md

@@ -49,8 +49,25 @@ without requiring a retry.
 It copies the runtime into `~/Library/Application Support/Token Meter/runtime`,
 so the cloned folder is not used for automatic startup.
 
-Token Meter starts its local server and menu bar widget automatically after
-installation and after future logins. Open the dashboard at:
+On Windows, install Python 3.8 or newer, clone the repository, and run the
+per-user PowerShell installer. The official ARM64 Python build can be installed
+with Winget:
+
+```powershell
+winget install --exact --id Python.Python.3.13 --architecture arm64 --scope user
+git clone https://github.com/Galileo-Agent-Labs/token-meter.git
+pwsh -NoProfile -File .\token-meter\scripts\install-windows.ps1
+```
+
+The Windows installer stages the runtime under
+`%LOCALAPPDATA%\Token Meter\runtime`, starts the local server without a console
+window, starts a Windows system-tray widget, and registers one per-user login
+startup entry for both processes. The AppKit menu-bar companion remains
+macOS-only; Windows uses its own built-in `NotifyIcon` companion.
+
+Token Meter starts its local server automatically after installation and after
+future logins. It also starts the menu bar widget on macOS or the system-tray
+widget on Windows. Open the dashboard at:
 
 ```text
 http://localhost:8722
@@ -187,17 +204,19 @@ observation establishes a baseline and never sends a catch-up notification.
 ## Requirements
 
 - Python 3.8 or newer. The macOS package first tries `/usr/bin/python3`, then
-  Homebrew and user `python3` installs.
+  Homebrew and user `python3` installs. The Windows installer detects native
+  Python installs under `%LOCALAPPDATA%\Programs\Python` as well as `PATH`.
 - Claude Code CLI, Codex CLI, Claude Desktop Agent/Cowork, and/or the Codex
   desktop app if you want live log data.
-- macOS with the Swift toolchain, usually from Xcode Command Line Tools, when
-  running from source. The macOS package includes a prebuilt menu bar binary.
-- `curl`, used by the helper scripts.
+- macOS with the Swift toolchain, usually from Xcode Command Line Tools, for the
+  native menu-bar companion. The macOS package includes a prebuilt binary.
+- Git. The macOS helper scripts also use `curl`; Windows uses PowerShell's local
+  HTTP client.
 
 The web dashboard has no third-party Python packages. `meter.py` uses only the
-Python standard library. Dashboard-only mode is available for development,
-troubleshooting, and non-macOS use, but the normal experience includes the menu
-bar companion.
+Python standard library. The Windows tray uses the Windows PowerShell and
+WinForms components included with Windows; the macOS menu-bar companion uses
+AppKit.
 
 ## Ask From Codex Or Claude
 
@@ -239,6 +258,10 @@ codex mcp add --env TOKEN_METER_CALLER=codex tokenmeter -- "$PWD/scripts/run-tok
 claude mcp add --transport stdio --scope user tokenmeter --env TOKEN_METER_CALLER=claude -- "$PWD/scripts/run-token-meter-mcp"
 ```
 
+The Windows installer stages an equivalent launcher at
+`%LOCALAPPDATA%\Token Meter\runtime\scripts\run-token-meter-mcp.cmd`; the
+dashboard's connection controls select it automatically.
+
 Remove the connections with:
 
 ```bash
@@ -257,7 +280,7 @@ updates**. Token Meter immediately fetches revision metadata from the Git
 upstream configured during installation, then checks again once per hour while
 the server is running. The installer keeps a dedicated update checkout beside
 the runtime so the background service does not need access to a development
-checkout under a macOS-protected folder such as Documents. You can disable
+checkout instead of the development clone. You can disable
 these checks at any time. Checks do not merge, pull, reinstall, or send
 telemetry.
 
@@ -279,21 +302,31 @@ either process independently if it exits. Remove both login items with:
 "$HOME/Library/Application Support/Token Meter/runtime/scripts/uninstall-launch-agent"
 ```
 
+On Windows, the installer registers a launcher for the server and tray widget in
+the current user's `Run` key. Remove that startup entry and stop both processes
+while retaining the staged runtime with:
+
+```powershell
+& "$env:LOCALAPPDATA\Token Meter\runtime\scripts\uninstall-windows.ps1"
+```
+
 ## Dashboard-Only Mode
 
-For development, troubleshooting, or non-macOS use, run only the local web
+For development or troubleshooting, run only the local web
 dashboard:
 
 ```bash
 python3 meter.py
 ```
 
-The menu bar companion polls the local `/menubar` endpoint. Run shows compact
-status for the active log; All and the provider tabs show cached account quota
-snapshots. The Recent sessions section labels each entry as Claude, Codex, or
-Cursor, uses the session title or project as an identifier, and keeps a selected
-pin in macOS preferences. Choose `Follow Latest` to resume automatic tracking.
-The companion does not parse logs or read provider credentials directly.
+The macOS menu bar and Windows tray companions poll the local `/menubar`
+endpoint. The Windows tray tooltip shows compact estimated spend and guidance;
+its menu provides live activity, recent-session selection, dashboard deep
+links, refresh, and quit actions. Left-click the Token Meter tray icon to open
+the dashboard; right-click it to open the tray menu. The macOS companion also
+shows cached provider quota snapshots. Choose `Follow Latest` to resume
+automatic tracking. Neither companion parses logs or reads provider credentials
+directly.
 
 ## How It Finds Logs
 
@@ -637,8 +670,11 @@ The final command requires at least one supported local Claude, Codex, or Cursor
 |   `-- TokenMeterMenuBar.swift      # native macOS menu bar companion
 |-- scripts/
 |   |-- install                      # install the local runtime and login items
+|   |-- install-windows.ps1          # install the Windows runtime and startup
 |   |-- run-menubar                  # build and run the menu bar companion
+|   |-- run-tray.ps1                 # run the Windows system-tray companion
 |   |-- start-token-meter            # start server if needed, then menu bar
+|   |-- start-token-meter.ps1        # start Windows server and tray
 |   |-- install-launch-agent         # install server and menu login items
 |   `-- uninstall-launch-agent       # remove both macOS login items
 |-- REQUIREMENTS.md                  # product rationale and historical notes