codex-monitor_skill

Overview

This skill provides command-line helpers to browse and monitor OpenAI Codex session logs stored on a local machine. It wraps a small Swift project to list, show, and watch session activity, exposing text and JSON outputs. Use it to quickly inspect historical sessions or run a live monitor in the menu bar.

How this skill works

The skill calls Swift executables from the local project at ~/Developer/CodexMonitor, using the CLI and app targets. Commands run via the Python wrapper invoke the Swift CLI (swift run CodexMonitor-CLI ...) or launch the menu bar monitor (swift run CodexMonitor-App). Extra arguments are passed through to the underlying CLI so behavior can evolve with the Swift project.

When to use it

• Inspect sessions for a specific day, month, or year to audit activity.
• Show the full content of a single session or specific message ranges.
• Export session data as JSON for analysis or backups.
• Watch live updates for all sessions or a single session during active work.
• Launch the menu bar monitor for continuous, low-friction observability.

Best practices

• Build the Swift project once (swift build) if swift run is slow during iterative use.
• Use JSON output (--json) when piping results into tools, scripts, or analytics pipelines.
• Specify ranges when showing long sessions to limit output and focus on relevant messages.
• Run watch only for specific sessions when monitoring a single thread to reduce noise.
• Keep the project at ~/Developer/CodexMonitor so the wrapper can find and run the executables.

Example use cases

• List all sessions on 2026/01/08 to review work performed that day.
• Show session ABC123 and display messages 1...3 and 26...28 to extract key interactions.
• Run list --json for a month to import session metadata into a reporting tool.
• Watch --session ABC123 while a colleague reproduces an issue to observe live messages.
• Launch the monitor in the menu bar to get passive updates on new or changing sessions.