Skip to content

ACTIVITY_DOTS.md

Latest commit

 

History

History
82 lines (59 loc) · 3.37 KB

ACTIVITY_DOTS.md

File metadata and controls

82 lines (59 loc) · 3.37 KB
Raw

Activity dots

Activity dots show whether Codex is working without estimating activity from rate-limit changes. The widget receives lifecycle signals from official local Codex hooks and keeps the state in memory.

Back to the README

What the widget tracks

  • One quiet dot while Codex is idle and a three-dot wave while work is active
  • Start and completion events for parallel Codex sessions
  • One active turn per session, so one completed session cannot hide another active session
  • A completion animation after the final active turn finishes

The widget accepts only the lifecycle event type and the session and turn identifiers provided by Codex. It does not collect prompts, responses, transcript contents, transcript paths, or model output.

Set up in the widget

  1. Open Settings from the desktop widget, taskbar-label menu, or tray menu, then find Codex activity under Features.
  2. Select Install hooks.
  3. Review the exact proposed ~/.codex/hooks.json content and confirm the change.
  4. Select Copy /hooks and open Codex.
  5. Paste /hooks into Codex and trust the new UserPromptSubmit, Stop, and SessionEnd definitions.
  6. Return to Settings and select Check again.

Codex owns hook trust. New or changed definitions require approval in Codex. The widget only reads the reported trust state.

To remove the handlers, return to Codex activity under Features in Settings and select Remove hooks. The widget preserves unrelated hooks and unknown configuration fields.

Command-line setup and removal

The same review-before-write flow is available from PowerShell in the directory containing the widget executable:

.\CodexUsageWidget.exe --install-activity-hooks

To remove the recognized Codex Usage Widget handlers:

.\CodexUsageWidget.exe --uninstall-activity-hooks

The setup code recognizes only the exact command formats generated by current and earlier portable versions of Codex Usage Widget. Similarly named handlers from other applications are left unchanged.

Privacy and local transport

  • Hook signals stay on the current Windows account through a current-user-only named pipe.
  • A small PowerShell bridge sends the signal without starting the WPF widget for each event.
  • Activity state is never persisted, so the widget does not build a work history.
  • The widget does not read Codex authentication data.
  • No hook data is sent to telemetry, analytics, or a remote backend.

Hook installation is always explicit. Normal widget startup does not create or modify hook configuration.

Runtime behavior and recovery

Activity state starts empty when the widget starts. A task that began before the widget or hooks were ready cannot be reconstructed.

Each session owns at most one active turn. A later UserPromptSubmit replaces an orphaned turn in that session, and a late Stop for the old turn cannot clear the new one. Duplicate events are harmless. SessionEnd removes only the matching session.

If Codex terminates without sending a final lifecycle event, a later turn in the same session replaces the stale turn. Restarting the widget also clears all in-memory activity state. The widget does not use an arbitrary timeout because legitimate Codex tasks can run for a long time.

If the widget is closed, the hook bridge exits successfully after a short connection attempt and Codex continues normally.