Codex Observability

Local‑only observability dashboard for Codex CLI usage. This app reads your local Codex data in ~/.codex and visualizes activity, tokens (including cache), model calls, tool‑call success rates, durations, and more. For projects, maps multiple folders or workspaces against single github remote repo.

What it does

• Live dashboard for tokens, cache utilization, model calls, and sessions
• Tool‑call analytics: success rate, failures, duration trends
• Activity heatmap + per‑session details
• Local‑only storage (SQLite), no outbound telemetry

Data sources (local)

• ~/.codex/sessions/**/rollout-*.jsonl (session events)
• ~/.codex/history.jsonl (first prompt timestamp)
• ~/.codex/log/codex-tui.log (tool call logs)

Tech stack

• Next.js (App Router) + TypeScript
• shadcn/ui + Tailwind
• Recharts via shadcn chart components
• SQLite (local)

Getting started

Install deps:

pnpm install

Run dev server:

pnpm dev

Build:

pnpm build

Start production server:

pnpm start

Smoke scripts:

pnpm ingest:smoke
pnpm log:smoke

E2E API tests (builds app, starts server, validates all API endpoints):

pnpm test:e2e

Notes

• This app is designed to run locally and read from your ~/.codex directory.
• No data is sent externally.
• pnpm dev runs a full ingest before starting the server so dashboard data is up to date.

Missing or stale data?

If the heatmap, activity, or token counts look wrong or are missing recent days:

pnpm ingest:full

Then refresh the dashboard. This re-ingests all Codex session files from scratch (incremental ingest can miss data when files were still being written).

Project plan

See INIT.md for architecture, schema, and execution plan.

UI docs

See docs/shadcn.md for shadcn/ui setup and chart notes.

Lines of code: 20,683 (2025-02-01).