Skip to content

README.md

Latest commit

 

History

History
119 lines (80 loc) · 2.98 KB

README.md

File metadata and controls

119 lines (80 loc) · 2.98 KB

CodexMonitor

Tools for listing, inspecting, and watching local OpenAI Codex sessions.

By default it reads sessions from:

  • ~/.codex/sessions

Overrides:

  • CODEX_SESSIONS_DIR → absolute sessions directory (e.g. /Users/alice/.codex/sessions)
  • CODEX_HOME → uses $CODEX_HOME/sessions

Works with sessions created from:

  • the Codex CLI (codex exec …, codex exec resume …)
  • the VS Code Codex extension

What’s included

  • CodexMonitor-CLI: list/show/watch Codex sessions
  • CodexMonitor-App: macOS menu bar app showing recent/active sessions and letting you view session messages

Build

swift build

CodexMonitor-CLI

List sessions

swift run CodexMonitor-CLI list 2026/01/08
swift run CodexMonitor-CLI list 2026/01
swift run CodexMonitor-CLI list 2026

Output format:

<id>\t<start->end>\t<cwd>\t<title>

(Exact formatting may evolve, but the intent is: session id, time range, project path, title/origin.)

Title heuristics:

  • Uses the first user message (skipping AGENTS and <environment_context>).
  • If the message contains a ## My request for Codex: section, only that section is used.
  • Removes local file paths like /Users/.../File.swift:12:3.
  • Newlines are replaced with spaces and the result is truncated.

Show a session

swift run CodexMonitor-CLI show <session-id>
swift run CodexMonitor-CLI show <session-id> --ranges 1...3,25...28

Outputs messages as markdown with headers and strips <INSTRUCTIONS> blocks.

Pretty JSON export:

swift run CodexMonitor-CLI show <session-id> --json
swift run CodexMonitor-CLI show <session-id> --json --ranges 1...3,25...28

Watch sessions

swift run CodexMonitor-CLI watch
swift run CodexMonitor-CLI watch --session <session-id>

Prints a line for each new or updated .jsonl session file.

CodexMonitor-App (Menu Bar)

swift run CodexMonitor-App

The menu bar app:

  • shows the most recent sessions (and indicates which ones are currently active)
  • lets you open a session and view the session messages in a window

Learnings / Notes

Where Codex stores sessions

Codex sessions are stored as JSONL files under (default):

~/.codex/sessions/YYYY/MM/DD/

If you have a non-standard setup, set one of:

  • CODEX_SESSIONS_DIR (preferred)
  • CODEX_HOME (uses $CODEX_HOME/sessions)

Resuming sessions by id

Codex can append to an existing session by id:

codex exec resume <SESSION_ID> "message"

Key behavior:

  • resume does not create a new session
  • resume does not move the session file to “today” — it stays in its original YYYY/MM/DD folder (only mtime changes)

VS Code refresh behavior

When you append to a session (e.g. via codex exec resume …), VS Code may not immediately show the new messages. A restart of VS Code reliably refreshes the session view.

Notes

  • Session lookup is filename-based for speed (the session id must appear in the .jsonl filename).