CodexInspector

A native macOS menu bar app that reads local Codex session logs and shows live token usage with charts.

What it shows

• Active session tokens (live from the most recently updated session)
• Compact popover view with quick hourly graph and "Open Dashboard" action
• Aggregated tokens for:
  • last hour
  • today
  • all time
• Charts:
  • by session
  • over time (hour, day, week buckets)
• Recent sessions list with timestamp, session name, project, and per-session totals
• Session inspector: on-demand per-turn deep inspection with markdown-formatted context, raw JSON, and paginated tool calls/large payloads
• Live turn inspector mode (1-5s polling) with per-turn token deltas and in-progress turn visibility
• API-equivalent cost metrics (session/day/all-time) with configurable fallback pricing
• Per-session model detection and model-aware OpenAI pricing for known models
• OpenAI pricing presets for fallback/custom overrides

Data source

The app reads local JSONL files from:

• ~/.codex/sessions/**/*.jsonl
• optional: ~/.codex/archived_sessions/*.jsonl

It parses event_msg records where payload.type == "token_count" and uses info.total_token_usage snapshots. It also derives session names from first user_message records, parses turn_context to detect model usage, and performs deep turn inspection on demand.

Run

swift build
swift run

The app launches as a menu bar utility (no dock icon).

Troubleshooting

• If you do not see the item immediately, check macOS menu bar overflow or Control Center (your menu bar may be full).
• Quit old instances before relaunching:

  pkill -f CodexInspector || true
  swift run

Settings (inside the menu bar panel)

• Codex home path (default ~/.codex)
• Include archived sessions toggle
• Refresh interval (2 to 30 seconds)
• Fallback API pricing rates ($ per 1M) for input, cached input, output, reasoning

Cost notes

• Costs shown are API-equivalent estimates from local token logs.
• OpenAI ChatGPT/Codex seat fees, included Business usage, and purchased credits are not exposed as per-session billed dollars in the local JSONL logs.
• Known OpenAI models use built-in model-specific pricing automatically; custom settings are used as fallback for unknown models.

Project layout

• Sources/CodexInspector/CodexInspectorApp.swift: app entry + menu bar scene
• Sources/CodexInspector/DashboardView.swift: UI and charts
• Sources/CodexInspector/TokenUsageStore.swift: refresh loop, aggregation, view state
• Sources/CodexInspector/TokenUsageService.swift: JSONL discovery, parsing, file cache
• Sources/CodexInspector/Models.swift: shared models and bucket metadata
• Sources/CodexInspector/Formatters.swift: token formatting helpers

Roadmap

• Daily budget + burn rate tracking
• Cost estimation mode with configurable pricing profiles
• Model/provider breakdown charts
• Project/worktree attribution (cwd grouping)
• Usage spike/anomaly detection
• Top sessions explorer (tokens total + tokens/minute)
• Session search index for fast lookup by conversation topic/keywords
• Native notification thresholds and alerts
• Menu bar micro-sparkline trend
• CSV/JSON export and optional local API endpoint
• launchd background collector for always-warm cache
• End-of-day/week usage forecasting
• Day-over-day and week-over-week comparison views