Codex Thread Inspector
https://github.com/jarrodwatts/codex-thread-inspector- Category
- AI Agents
- Rank
- No. 1833Tools index
Previous survey · No. 1841 ·
- Pricing
- Open Source
- Type
- TOOL
- Builder
- jarrodwatts
- GitHub
- 1 stars
- Date
About
Visualize Codex agent session internals — timeline, token usage, tool calls, and context layers.
What it does
Codex Thread Inspector turns Codex rollout logs into a browsable local web application. It automatically finds sessions in the standard Codex directory, or accepts a JSONL file through drag and drop, then organizes each session into turns, messages, commands, searches, reasoning summaries, context changes, and usage data.
Why it's ranked here
This is a focused diagnostic tool with unusually useful visibility into agent behavior. It connects prompts, model settings, tool activity, and token consumption within the same session view. The source also handles several rollout event shapes, making the presentation more informative than simply pretty-printing JSONL records.
What's good
The parser tolerates malformed lines and normalizes function calls, custom tools, shell commands, web searches, compactions, and messages into one model. It separates cumulative and per-turn token figures, reports cache usage, deduplicates repeated instructions, supports keyword filtering, and lets users inspect standalone rollouts without installing Codex.
Tradeoffs
Setup requires cloning the repository, installing dependencies with pnpm, and running a development server. Automatic discovery depends on the Codex directory layout and reads each candidate session file to obtain its header. Malformed lines and unsupported event types are silently skipped, which can hide incomplete parsing. Search filters whole turns rather than individual matching events.
How to use it well
Use it when debugging why a Codex session behaved unexpectedly, comparing token patterns across turns, or checking which instructions and execution policies reached the model. Upload mode suits shared or archived rollout files. It is an inspector, not an editor, replay system, session runner, or general observability service.
Technical notes+
The private TypeScript application uses Next.js 16 and React 19, declared in package.json. src/lib/sessions.ts traverses the standard session hierarchy or CODEX_SESSIONS_DIR, reads session headers, and sorts discovered records by timestamp. src/lib/parser.ts parses JSONL line by line, ignores invalid JSON, and maps known rollout records into the interfaces defined in src/lib/models.ts. src/lib/viewmodel.ts derives session statistics, deduplicated context collections, serialized timeline entries, token snapshots, and per-turn token deltas. src/hooks/use-search.ts builds lowercase JSON indexes and applies a 200 millisecond debounce. src/components/upload-zone.tsx reads selected JSONL files with FileReader and routes users to the uploaded-session view.
Observed
- License
- MIT
- Primary language
- TypeScript
- Packaging
- Private Next.js application installed with pnpm
- Interface
- Local web UI with automatic session discovery and JSONL file upload
- Runtime requirements
- Node.js 18 or newer and pnpm; Codex CLI is optional when using upload mode
- Framework surface
- Next.js 16 with React 19
Read from README.md, package.json, src/app/page.tsx, src/lib/utils.ts, src/lib/format.ts, src/lib/models.ts, src/lib/parser.ts, src/app/layout.tsx, src/lib/sessions.ts, src/lib/viewmodel.ts, src/hooks/use-search.ts, src/hooks/use-session.ts, src/components/search-bar.tsx, src/components/copy-button.tsx, src/components/upload-zone.tsx.
What it can do
Visualize Codex agent session timeline
Codex agent session data → Timeline visualization of session events
Track token usage across sessions
Codex agent session data → Token consumption metrics and statistics
Display tool call sequences
Codex agent session data → Visual representation of tool calls and their order
Inspect context layers
Codex agent session data → Hierarchical view of context information
Analyze session internals
Codex agent session data → Detailed breakdown of internal session components
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.