Skip to content

ACTIVITY_DOTS.md

Latest commit

 

History

History
94 lines (69 loc) · 4.31 KB

ACTIVITY_DOTS.md

File metadata and controls

94 lines (69 loc) · 4.31 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 hooks. While activity is present, it also checks turn completion metadata through the official local app-server protocol, with turn items omitted. 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.

While activity is present, the widget checks every 15 seconds whether each tracked turn has finished. It uses thread/turns/list with itemsView: "notLoaded", follows pagination, and clears a turn only when its exact identifier has a terminal status and an explicit completion timestamp. A late result cannot clear a newer turn in the same session. No checks are sent while idle, and each turn's check has a five-second request timeout.

This requires a Codex CLI that supports thread/turns/list and completion timestamps, verified with CLI 0.154.0. Unsupported requests, unavailable history, missing turns, and failed checks leave hook activity unchanged. In particular, a separate app-server can reconstruct a running turn as interrupted without a completion timestamp; that is not evidence of completion.

If Codex terminates without recording completion or 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 never expires activity solely because a task has run for a long time.

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