Codex Session Light

Codex Session Light adds a small status bar indicator for Codex sessions in VS Code.

It is a companion indicator based on local Codex rollout logs. It does not read or mirror the private UI state of the official Codex VS Code extension.

Its main purpose is to alert you when Codex is waiting for confirmation. Its second purpose is to show when a running task has finished and you can send the next input.

Status

• Green: a Codex session in the current workspace appears to be running.
• Yellow: a Codex session in the current workspace appears to need blocking confirmation, permission, or user input before it can continue.
• Red: no Codex task appears to be running. This includes completed, idle, stopped, and failed tasks.

When multiple sessions are found, the priority is:

Blocking confirmation yellow > Running green > Stopped red

Failures and network exceptions are shown as red because the task is no longer running, with a failure reason in the tooltip and the exception sound when enabled.

Scope

By default, each VS Code window only tracks Codex sessions whose logged cwd is inside that window's workspace:

"codexSessionLight.sessionScope": "workspace"

Use this mode when you want each VS Code window to show the state for its own project.

To track every local Codex session, including sessions from other workspaces or CLI runs, set:

"codexSessionLight.sessionScope": "all"

Important Limitations

This extension infers state from files under:

~/.codex/sessions/**/rollout-*.jsonl

It is not an official Codex UI state mirror. The official Codex extension does not currently expose a public API for its active UI state, selected task, task list, webview state, or "apply these changes" modal.

Because of that:

• The indicator can approximate session activity, completion, explicit approval waits, and common terminal/tool error states.
• It cannot guarantee exact parity with the Codex sidebar UI.
• The Codex UI's blocking confirmation prompts are inferred from approval/user-input events in rollout logs.
• Tool calls with sandbox_permissions: require_escalated are treated as yellow because the Codex UI is waiting for permission.
• File-change application prompts such as "apply these changes" are treated as yellow when a rollout apply_patch call has been emitted but the matching patch_apply_end or tool output has not appeared yet.
• Official Codex VS Code extension logs are used as an additional hint for approval dialogs, but only when a rollout session is already running.
• The non-blocking edited-files review card with actions such as review or undo is treated as red because the Codex task has completed.
• Reconnect/retry messages are not treated as errors by default; an error state is intended for failed tool outputs or explicit failure events.

Privacy

Codex Session Light reads local Codex rollout logs and local VS Code extension logs to infer session state. It does not send log content, file paths, prompts, or telemetry to any remote service. All state detection runs locally inside VS Code.

Sounds

The extension can play local system sounds for state changes:

• Waiting confirmation: Ping.aiff
• Task completed: Glass.aiff
• Error or network failure: Basso.aiff

Click the status bar item to toggle sounds on or off. The status bar shows a bell or mute icon.

Settings

• codexSessionLight.sessionsDir: defaults to ~/.codex/sessions.
• codexSessionLight.sessionScope: defaults to workspace.
• codexSessionLight.pollIntervalMs: defaults to 250.
• codexSessionLight.idleTimeoutMs: defaults to 600000.
• codexSessionLight.activeLogGraceMs: defaults to 10000.
• codexSessionLight.maxSessionLogs: defaults to 20.
• codexSessionLight.completionGraceMs: defaults to 5000.
• codexSessionLight.waitingDebounceMs: defaults to 500.
• codexSessionLight.soundsEnabled: defaults to true.
• codexSessionLight.waitingSoundEnabled: defaults to true.
• codexSessionLight.waitingSoundDelayMs: defaults to 1000.
• codexSessionLight.completedSoundEnabled: defaults to true.
• codexSessionLight.exceptionSoundEnabled: defaults to true.
• codexSessionLight.officialCodexLogHintsEnabled: defaults to true.
• codexSessionLight.officialCodexLogsDir: defaults to the platform VS Code logs directory.
• codexSessionLight.officialApprovalTimeoutMs: defaults to 120000.

waitingDebounceMs filters transient false positives, but a real confirmation that remains in the log will still turn yellow. completionGraceMs keeps the indicator green briefly after task_complete so the Codex UI can finish rendering final output. activeLogGraceMs is a fallback for cases where the log is still being updated but the latest event is ambiguous. The extension reads the latest 240 rollout log lines per inspected session so pending file-change approvals are less likely to be missed in busy sessions.

The official Codex log hint is a fallback for VS Code UI approval dialogs that are visible in the official extension log but not clearly represented in rollout JSONL. It only uses explicit request-approval log entries and does not create a yellow state by itself when no Codex rollout session is running.

During local validation, the official Codex log sometimes recorded a real file-change confirmation as Item not found in turn state itemId=... before the user responded, followed by Sending server response ... method=item/fileChange/requestApproval after the user accepted or declined. Because Item not found can also appear without a visible confirmation dialog, this extension does not treat that message alone as yellow. Instead, file-change yellow detection is anchored to the rollout apply_patch call lifecycle.

Commands

• Codex Session Light: Refresh
• Codex Session Light: Open Latest Log
• Codex Session Light: Show Diagnostics
• Codex Session Light: Toggle Sounds
• Codex Session Light: Enable Sounds
• Codex Session Light: Disable Sounds
• Codex Session Light: Test Waiting Sound

Use Codex Session Light: Show Diagnostics when the visible light disagrees with the Codex UI. It shows the current inferred state, the matched Codex cwd, the current VS Code workspace root, the rollout log path, and the last log update time. This is the fastest way to tell whether the extension is reading a different workspace/session or whether the rollout log itself is missing a clear running/waiting signal.

Sounds are only played on state transitions after the extension has initialized. If VS Code is reloaded while Codex is already waiting for confirmation, the indicator may start yellow without playing the waiting sound. Use Codex Session Light: Test Waiting Sound to verify local sound playback.

The yellow indicator is shown immediately, but the waiting-confirmation sound is delayed by waitingSoundDelayMs. If the confirmation is resolved before the delay expires, the sound is canceled. This keeps the visual signal fast while giving the official Codex dialog time to render before the audible alert.

Troubleshooting Red While Codex Is Running

If Codex is visibly running but the indicator is red:

1. Run Codex Session Light: Show Diagnostics.
2. Compare Workspace with Codex cwd.
3. If Codex cwd is not inside Workspace, the session is being excluded by the default workspace scope.

Example:

Workspace: /Users/example/project-a
Codex cwd: /Users/example/project-b

With the default setting, this is expected to show red in the project-a window because the active Codex session belongs to project-b.

To make one VS Code window track every local Codex session, set:

"codexSessionLight.sessionScope": "all"

Keep the default workspace scope when each VS Code window should track only its own project. Use all when you want the light to represent any Codex activity on the machine, including other VS Code windows or CLI sessions.