Codex & Claude History Viewer

Local-first, dependency-free web viewer for Codex CLI and Claude Code session logs.

• Browse sessions and projects (work dirs)
• Search sessions by keyword + date range
• Filter messages by role, and search within a session (highlight + next/prev)
• Sort sidebar by start time or last activity
• Highlight interruptions and common error outputs

Not affiliated with OpenAI or Anthropic. “Codex” and “Claude” are trademarks of their respective owners.

Why

Codex CLI and Claude Code both generate local, machine-readable transcripts (JSONL). This project turns those logs into a fast, searchable “history inbox” you can use to:

• find past commands/patches/discussions quickly
• audit tool failures and interruptions
• compare sessions across days/projects
• keep everything local (no uploads by default)

Quick start

Requirements:

• Python 3.8+ (standard library only)
• A modern browser

Run:

python3 app.py

or install and use the global CLI:

CCHV install
CCHV serve

Open:

• http://127.0.0.1:8787

By default it reads:

• Codex logs: ~/.codex/sessions
• Claude logs: ~/.claude/projects

Indexes (SQLite) are stored by default in ~/.cache/cchv (or $XDG_CACHE_HOME/cchv) unless you set --data-dir.

Configuration

Show all options:

python3 app.py --help

CCHV subcommands:

CCHV --help
CCHV serve --help
CCHV demo --help
CCHV install

Demo data (included)

This repo includes a small set of synthetic Codex/Claude logs under demo/ so you can try the UI without using your own transcripts.

python3 app.py \
  --codex-dir ./demo/codex \
  --claude-dir ./demo/claude \
  --data-dir ~/.cache/cchv/demo

Common examples:

# Store indexes outside the repo (recommended)
python3 app.py --data-dir ~/.cache/cchv

# Same thing via the bundled CLI
CCHV serve --data-dir ~/.cache/cchv

# Bind to LAN (be careful: your logs may contain secrets)
python3 app.py --host 0.0.0.0 --port 8787

# Launch with bundled synthetic logs
CCHV demo

# Install CCHV into ~/.local/bin so it works globally
CCHV install

# Custom log locations (these are the *base dirs* that contain `sessions/` and `projects/`)
python3 app.py --codex-dir ~/.codex --claude-dir ~/.claude

# Faster/slower auto-rescan (seconds)
python3 app.py --scan-interval 2

Using the UI

• Source: switch between Codex / Claude Code logs.
• Browse:
  • Sessions: list individual sessions.
  • Projects: group sessions by working directory (cwd).
• Sidebar sort: top-right dropdown in the sessions list:
  • Start time (default)
  • Last activity
• Roles: toggle user/assistant/system/developer/tool/other.
• Role jump: click a message on the right, then use each role row’s ▲/▼ buttons to jump across that role. The n/m counter shows the selected message’s position within that role.
• Search
  • Left panel: keyword search across sessions + optional date range, with a keyword clear button.
  • Right panel: search within the opened session (highlight + ▲/▼ navigation). The summary uses n/m format.
• Error highlighting
  • User interruptions (e.g. turn_aborted) are highlighted.
  • Common tool failures (HTTP 4xx/5xx, Traceback/Exception, Status: error, etc.) are highlighted.

Privacy & safety notes

• Your local transcripts may contain sensitive info (API keys, file paths, proprietary code).
• If you bind --host 0.0.0.0, anyone on your network may be able to access the UI. Prefer 127.0.0.1.
• Index files are local SQLite databases; this repo’s .gitignore excludes them.

License

MIT (see LICENSE).