cchist

One place to browse, search and resume all your AI coding sessions — across Claude Code and Codex.

中文说明 →

Claude Code and Codex scatter every conversation into per-project folders (~/.claude/projects/…, ~/.codex/sessions/…). Over time they become impossible to navigate: --resume only shows an auto-generated title, and the sessions are spread across a dozen directories.

cchist flattens them all into one view. Search by title or full text, see the first & last message and turn counts, jump back into any session (it cds to the original directory and resumes), and safely clean up throwaway chats.

Two frontends, one core:

• Terminal TUI (default) — keyboard-driven, press Enter to resume seamlessly
• Web UI (cchist web) — nicer to read long transcripts, export, and view stats

Features

Install

pip install --user "cchist[web]"     # from PyPI, with the web UI
# or from source:
git clone https://github.com/Zephyrus704/cchist.git && cd cchist && pip install --user ".[web]"

If cchist: command not found, add ~/.local/bin to your PATH: export PATH="$HOME/.local/bin:$PATH".

Usage

cchist              # terminal UI (default)
cchist web          # web UI (opens the browser)
cchist web --port 9000 --no-browser
cchist --help

TUI keys

Web UI notes

cchist web starts a local server (default http://127.0.0.1:8770).

• Stop it from the terminal with Ctrl+C, or click ⏻ Stop server in the top-right. ⚠️ Closing the browser tab does not stop the server.
• It binds to 127.0.0.1 only. Do not expose it with --host 0.0.0.0.

How it works

Each tool stores sessions as JSONL with the working directory and every message:

• Claude Code — ~/.claude/projects/<slug>/<session-id>.jsonl
• Codex — ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl

cchist only reads them. A small Provider abstraction (providers.py) knows each tool's location, format and resume command; everything else (trash, search, sort, export, UI) is provider-agnostic. Resume writes a signal file, then the CLI wrapper os.execvps into the real tool so the terminal is handed over cleanly.

cchist never modifies your conversation files — it only moves/deletes them, and deletes go to a recoverable trash first.

Override storage locations with CLAUDE_CONFIG_DIR and CODEX_HOME.

Project layout

src/cchist/
├── config.py      path config
├── providers.py   per-tool adapters (Claude, Codex)
├── core.py        data layer: scan / parse / search / trash / export (stdlib only)
├── resume.py      cross-platform resume
├── i18n.py        English / 中文 strings
├── tui.py         terminal UI (textual)
├── cli.py         CLI entry & subcommands
└── web/           FastAPI backend + build-free frontend

Development

pip install ".[dev,web]"
pytest

License

MIT