feat(codex): native overlay integration, CDP-free (deprecate CDP adapter)

CHANGELOG.md

@@ -4,6 +4,16 @@ The top entry is the current source version. Binary release metadata appears at
 `/api/v1/latest` only after a signed and notarized DMG has actually been
 published.
 
+## Unreleased
+
+- The Token Widget overlay now meters Codex natively. It reads the active thread
+  from Codex's local state database and its rollout files, so a frontmost Codex
+  window gets a bound face without a CDP debugging port, launch flags, or any
+  quit/relaunch of Codex. The overlay installs and runs on machines without
+  Claude installed, and the app is now named "Token Widget".
+- Deprecated the Codex CDP adapter (`scripts/install-token-meter-macos.sh`). It
+  still works but will be removed in a future release; prefer the app.
+
 ## 0.3.1 — 2026-08-15
 
 - Fixed the first aggregate sync for installations whose local Codex history

INSTALL_WITH_AGENT.md

@@ -62,7 +62,7 @@ Finish only when each selected host is installed and its real runtime status has
    ./scripts/status-claude-meter-macos.sh --json
    ```
 
-   - If `accessibilityGranted` is `false`, open System Settings > Privacy & Security > Accessibility and ask the user to enable **Token Widget for Claude**.
+   - If `accessibilityGranted` is `false`, open System Settings > Privacy & Security > Accessibility and ask the user to enable **Token Widget**.
    - After approval, wait up to 60 seconds, polling no faster than every five seconds, until `running`, `accessibilityGranted`, and `overlayReady` are all `true`.
    - Treat `bridgeHealthy` and `sessionBound` as foreground Session checks. They may correctly remain `false` while Claude is hidden or not showing Code.
    - Do not restart Claude while waiting.

README.md

@@ -31,9 +31,9 @@ The signed and Apple-notarized DMG is the primary release channel:
 - [Download Token Widget for macOS](https://www.tokenwidget.app/download/token-widget.dmg)
 - [Latest GitHub release](https://github.com/SergioChan/token-meter/releases/latest)
 
-Open the DMG, drag **Token Widget.app** to **Applications**, and open it once. The app contains its own compatible Node.js runtime. The Claude Desktop overlay requires macOS Accessibility permission for **Token Widget**; it never asks for permission on behalf of Claude.
+Open the DMG, drag **Token Widget.app** to **Applications**, and open it once. The app contains its own compatible Node.js runtime. The overlay requires macOS Accessibility permission for **Token Widget**; it never asks for permission on behalf of Claude or Codex. The same app meters both Claude Code and Codex — it follows the frontmost host window and reads each host's local telemetry.
 
-The Codex Desktop adapter currently uses its per-user source installer described below. The repository also remains the development and recovery installation path for both hosts.
+The legacy Codex CDP adapter (the per-user source installer described below) is deprecated in favor of this overlay and will be removed in a future release. The repository also remains the development and recovery installation path for both hosts.
 
 > **Multi-device release gate:** this source tree contains the next-release Profile/device model and v2 aggregate sync protocol. Do not enable multi-device Profile reads in production until the additive database migration, reconciliation, and verification gates in [the migration runbook](docs/multi-device-migration.md) have all passed. Older v1 clients remain compatible during the rollout.
 
@@ -220,6 +220,13 @@ Or attach [INSTALL_WITH_AGENT.md](INSTALL_WITH_AGENT.md) to a capable local codi
 
 ### Codex Desktop
 
+The recommended way to meter Codex is the **Token Widget** app above — it now
+supports Codex natively, reading the active thread from Codex's local state with
+no loopback debugging port, no launch flags, and no quit/relaunch of Codex.
+
+> **Deprecated:** the CDP adapter below is kept for now and will be removed in a
+> future release. Prefer the app.
+
 ```bash
 ./scripts/install-token-meter-macos.sh
 ```
@@ -244,7 +251,7 @@ Check local build prerequisites and install without quitting Claude:
 ./scripts/status-claude-meter-macos.sh --json
 ```
 
-If the status reports `accessibilityGranted: false`, enable **Token Widget for Claude** in **System Settings → Privacy & Security → Accessibility**. `bridgeHealthy` and `sessionBound` may correctly remain false while Claude is hidden or no Code Session is focused.
+If the status reports `accessibilityGranted: false`, enable **Token Widget** in **System Settings → Privacy & Security → Accessibility**. `bridgeHealthy` and `sessionBound` may correctly remain false while Claude is hidden or no Code Session is focused.
 
 Use a specific compatible Node binary when required:
 

SECURITY.md

@@ -44,7 +44,7 @@ The Claude integration is designed to defend against accidental Session confusio
 
 - Verifies the canonical Claude.app path, bundle ID, signature, Anthropic Team ID, executable, and packaged model catalog before installation.
 - Builds a separate background application with its own bundle ID; it does not patch, inject into, replace, or re-sign Claude.app.
-- Requires Accessibility permission for `Token Widget for Claude.app` itself.
+- Requires Accessibility permission for `Token Widget.app` itself.
 - Requires exactly one eligible `AXWebArea` in the frontmost Claude focused window; links, extra route components, and multiple candidates fail closed.
 - Reads Accessibility roles and the exact WebArea URL for identity, then only button titles inside that same web area for an optional strict Context-window ratio. It does not read static text, values, descriptions, or message bodies.
 - Hides when Claude is not frontmost or when exact Session identity is missing or ambiguous.
@@ -57,7 +57,7 @@ Accessibility permission allows the companion to inspect UI elements exposed by
 
 Source builds are ad-hoc signed by default. Their code identity can change after rebuilding, which may require renewed Accessibility approval. They also record the selected external Node.js path; if that runtime is later removed, rerun the installer with a compatible runtime.
 
-Deleting the application does not automatically delete its macOS TCC decision. Revoke **Token Widget for Claude** in System Settings, or uninstall with `./scripts/uninstall-claude-meter-macos.sh --purge-state --reset-accessibility`.
+Deleting the application does not automatically delete its macOS TCC decision. Revoke **Token Widget** in System Settings, or uninstall with `./scripts/uninstall-claude-meter-macos.sh --purge-state --reset-accessibility`.
 
 ### Community identity and browser sessions
 

docs/architecture.md

@@ -149,7 +149,7 @@ The controller remains alive across later Codex launches and sleep/wake. `RunAtL
 
 ## Claude macOS companion lifecycle
 
-The Claude installer builds and signs an independent `Token Widget for Claude.app`, copies the minimum runtime into the user's Application Support directory, and loads a per-user LaunchAgent. Source builds use ad-hoc signing unless a stable identity is supplied. The executable owns a non-activating `NSPanel`; it never executes code inside Claude's renderer.
+The Claude installer builds and signs an independent `Token Widget.app`, copies the minimum runtime into the user's Application Support directory, and loads a per-user LaunchAgent. Source builds use ad-hoc signing unless a stable identity is supplied. The executable owns a non-activating `NSPanel`; it never executes code inside Claude's renderer.
 
 macOS Accessibility permission is granted to the companion, not to the repository shell and not to Claude.app. The process writes atomic `health.json` state from startup onward. Status validates its PID against the exact executable, checks Accessibility live, and reports UI readiness, bridge health, and exact Session binding independently. A permission-blocked companion remains alive and reports a waiting process without falsely reporting trust. It detects both grant and revocation quietly; it neither repeats the system prompt nor quits or relaunches Claude.
 

docs/claude-code.md

@@ -172,7 +172,7 @@ It does not read static text or conversation content to find the ratio. The mode
 The installer and runtime enforce these constraints:
 
 1. Verify official Claude.app before installation.
-2. Build a separate `Token Widget for Claude.app` with its own bundle identifier.
+2. Build a separate `Token Widget.app` with its own bundle identifier.
 3. Require Accessibility permission for that companion application itself.
 4. Inspect only roles and URLs during the shallow focused-window identity scan; read only exact Context-window button titles inside the selected web area for optional numerical enrichment.
 5. Keep local transcript and cloud event-cache parsing content-discarding.

docs/install-claude-desktop.md

@@ -10,7 +10,7 @@ The signed and Apple-notarized DMG is the normal installation path. Source build
 
 - macOS 13 or newer.
 - The official signed Claude Desktop application at `/Applications/Claude.app`.
-- Permission to enable **Token Widget for Claude** in System Settings > Privacy & Security > Accessibility.
+- Permission to enable **Token Widget** in System Settings > Privacy & Security > Accessibility.
 
 The DMG contains its own compatible Node.js runtime. Building from source additionally requires Git, Node.js 22.12 or newer, and Xcode Command Line Tools with Swift.
 
@@ -48,7 +48,7 @@ Or select Node.js explicitly:
 The installer performs these operations:
 
 1. Verifies the canonical Claude.app path, bundle identifier, Anthropic Team ID, code signature, executable, and packaged model catalog.
-2. Builds and signs `Token Widget for Claude.app` as a separate background application. Source builds use ad-hoc signing unless a stable identity is supplied.
+2. Builds and signs `Token Widget.app` as a separate background application. Source builds use ad-hoc signing unless a stable identity is supplied.
 3. Copies the numerical collector, shared metrics core, and shared meter runtime into an isolated install root.
 4. Writes and loads `com.sergiochan.token-meter.claude-desktop` as a per-user LaunchAgent.
 5. Requests Accessibility permission for the companion application itself.
@@ -57,7 +57,7 @@ To build only the local app bundle for inspection:
 
 ```bash
 ./integrations/claude-desktop/scripts/build-app.sh \
-  --output "$PWD/local-artifacts/Token Widget for Claude.app"
+  --output "$PWD/local-artifacts/Token Widget.app"
 ```
 
 That bundle still expects the repository runtime and a compatible local Node.js path. Run the installer for the complete runtime copy and LaunchAgent configuration.
@@ -77,13 +77,13 @@ If installation reports `Accessibility permission: required`:
 
 1. Open System Settings.
 2. Go to **Privacy & Security > Accessibility**.
-3. Enable **Token Widget for Claude**.
+3. Enable **Token Widget**.
 4. Wait up to two seconds for the already-running companion to observe the new permission.
 
 If the application is not listed, request the system prompt again:
 
 ```bash
-open -n -a "$HOME/Library/Application Support/Token Meter/Claude Desktop/Token Widget for Claude.app" \
+open -n -a "$HOME/Library/Application Support/Token Meter/Claude Desktop/Token Widget.app" \
   --args --prompt-accessibility
 ```
 

integrations/claude-desktop/native/Info.plist

@@ -13,7 +13,7 @@
   <key>CFBundleInfoDictionaryVersion</key>
   <string>6.0</string>
   <key>CFBundleName</key>
-  <string>Token Widget for Claude</string>
+  <string>Token Widget</string>
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>