Codex Trace

Browse, search, and live-tail Codex CLI session logs in a native desktop app and web UI. Renders turns, tool calls, token counts, and collaboration chains from ~/.codex/sessions/ JSONL files — with live SSE tailing for ongoing sessions.

Claude Code user? See claude-code-trace instead.

Features

• 3-panel layout: date-grouped session tree → turn list → turn detail
• All tool kinds: exec command, MCP tool, patch apply, web search, image generation, collab agent spawn/wait/close
• Live tailing: SSE-based updates for ongoing sessions
• Collaboration tracking: orchestrator + worker session linking
• Three JSONL formats: new (≥0.44), mid, and oldest (2025/08) session meta
• Docker support: headless web mode on port 1422

Install

Build from source

git clone https://github.com/PixelPaw-Labs/codex-trace.git
cd codex-trace
./script/install.sh       # builds frontend + installs Rust binary

codex-trace              # desktop app (default)
codex-trace --web        # web mode (opens browser)

Run from source (no install)

git clone https://github.com/PixelPaw-Labs/codex-trace.git
cd codex-trace
npm install

npm run tauri dev        # desktop app with hot reload
npm run dev:web          # web mode (opens browser)

Run in Docker (web mode only)

docker build -t codex-trace .
docker run --rm -p 1422:1422 \
  -v "$HOME/.codex/sessions:/home/app/.codex/sessions:ro" \
  codex-trace
# then open http://localhost:1422

Or with compose: docker compose up --build

Session format

Reads ~/.codex/sessions/YYYY/MM/DD/rollout-{ISO_TIMESTAMP}-{UUID}.jsonl files.

The sidebar reflects the folder structure exactly — date groups (YYYY/MM/DD) collapse and expand, with sessions shown underneath.

Configuration

Press , to open Settings and change the sessions directory. Default: ~/.codex/sessions.

Environment variables (for headless/Docker mode):

Variable	Default	Description
CODEXTRACE_HTTP_HOST	127.0.0.1	Bind host
CODEXTRACE_HTTP_PORT	11424	Bind port
CODEXTRACE_STATIC_DIR	—	Path to built frontend dist/

Development

npm install
npm run dev          # Vite dev server (frontend only)
npm run tauri dev    # Full Tauri app

# Verify
npm run check        # tsc + oxlint + oxfmt + cargo clippy/fmt/test

Contributing

PRs welcome. Run npm run check before submitting — it covers tsc, lint, format, and Rust tests in one command.