Claude Code History Viewer reads the session files your coding agents leave behind
desktop app to browse and analyze your Claude Code conversation history
At a glance
- What is it?
- A Tauri desktop app and a headless server that parse local conversation history from Claude Code, Codex CLI, Cursor, Aider and roughly two dozen other assistants into one searchable interface. The value is real if you have scattered JSONL and SQLite session stores; the risk is that it reads other tools' undocumented file formats.
- Who is it for?
- Adopt it if you have months of Claude Code or Codex CLI sessions and no way to search them, and start with a read-only pass: run the desktop build or cchv-server --serve against your existing ~/.claude/projects/ directory before trusting any export. Skip it if your history lives in a hosted product with no local files, or if you need a stable schema you can script against, because the provider parsers track file formats the upstream tools never promised to keep.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap CCHV fills: agents write history, none of them let you read it back
Every assistant listed in the README keeps its own transcript somewhere on disk, in its own format, with no cross-tool index. Claude Code writes JSONL under ~/.claude/projects/. Codex CLI writes session rollouts under ~/.codex/sessions/. Aider drops chat history into project directories. ForgeCode and Kiro use SQLite files. The README's framing is blunt about the consequence: assistants generate thousands of messages and provide no way to look back across them. CCHV is for the engineer who has run several of these tools for months and now wants to answer questions like which session burned the most tokens, what prompt preceded a particular edit, or how a refactor conversation actually unfolded. It is a local archive reader, not a proxy and not a recorder. Nothing is captured at inference time; the app reads files that already exist.
How the parsing actually works: per-provider adapters over local files
The architecture is a Tauri shell: a Rust backend that touches the filesystem and a React and TypeScript frontend that renders it. The README's provider table is effectively the adapter list, and the adapters are not uniform because the sources are not. Some providers are JSONL directories, some are SQLite databases, and some are VS Code globalStorage trees keyed by extension ID. The README notes that Open Interpreter reuses the Codex parser because it emits Codex-format rollouts, and that oh-my-pi shares the Pi parser as a fork. Amazon Q CLI shares a format with the Kiro CLI provider. That reuse is the honest picture of the design: where two tools converged on one format, one parser serves both, and where they diverged, a separate adapter exists. Cline, Roo Code and Kilo Code are handled as one family through VS Code globalStorage. Environment overrides are respected in places, with CONTINUE_GLOBAL_DIR for Continue.dev and INTERPRETER_HOME for Open Interpreter named in the table. That matters on machines where these tools were configured away from their defaults.
Installing it: three paths, one of which opens a port
Desktop installs come from release artifacts: a universal .dmg for macOS, an .exe or portable .zip for Windows x64, and an .AppImage for Linux x64. macOS users can use the tap instead: brew install --cask jhlee0409/tap/claude-code-history-viewer. The headless path is a separate binary, installed with brew install jhlee0409/tap/cchv-server or the shell installer at install-server.sh, then started with cchv-server --serve, which the README says serves on http://localhost:3727. Server mode is documented for Docker, VPS and systemd setups. The README's own guidance for that mode is to keep authentication enabled, and the mode table repeats it. That is the one operational decision worth slowing down for: the desktop app reads files only on the machine you are sitting at, while the server exposes the same local history to a browser, so the authentication setting is the difference between a personal archive and a network service. The README states the app is 100% offline, which describes the desktop default rather than the server you deliberately expose.
Where it breaks: undocumented formats and providers it cannot reach
The core limitation follows from the design. CCHV parses files written by other programs, and those formats are internal details of those programs. A Claude Code release that changes its JSONL record shape, or a Cursor update that moves Composer data, can silently break an adapter until the maintainer ships a fix. The release cadence in the repository (v1.27.0, v1.26.3, v1.26.2 within days of each other) is consistent with a project that has to keep pace with upstream changes, but nothing in the material guarantees how quickly a broken parser gets repaired. There is also a coverage boundary: the provider table documents locations for the tools it supports, and anything not in that list is simply absent. If your history lives inside a hosted product that never writes local session files, this tool has nothing to read. And read-only is a real constraint for some providers, GitHub Copilot among them per the README, so you cannot use CCHV to prune or edit those sessions.
Compared with simpler approaches: grep, jq, and hand-rolled scripts
The obvious alternative is not another GUI. It is grep over ~/.claude/projects/ plus jq over the JSONL, or a short script against the SQLite files. That approach wins on one axis: you control the schema assumptions, and you notice when a record shape changes because your script throws. It also composes with existing tooling and needs no install. What it does not give you is the cross-provider normalization, the token and cost views, or the recent-edits view that the README's screenshots show. Writing your own normalizer across twenty-nine formats, including VS Code globalStorage layouts and several distinct SQLite schemas, is a much larger project than it looks. The honest split: if you only ever use Claude Code and only need to find a string, grep is faster to set up and has no maintenance tail. If you want to compare token usage across Claude Code and Codex CLI sessions in one place, CCHV is doing work you would otherwise have to build and then keep building.
Maintenance cost and the MIT licence in practice
Two costs sit on top of the install. The first is upgrade frequency: with releases landing days apart, the parsers are clearly being adjusted as upstream tools move, and pinning an old build means pinning old format assumptions. The second is the server surface. If you run cchv-server, you own the systemd unit or container, the port, and the authentication configuration, and the README's own instruction to keep authentication enabled is the thing to check before any non-localhost bind. On licensing, the repository is MIT, which is permissive and places few conditions on use or redistribution. That is a statement about the licence identifier in the repository, not legal advice, and it does not settle questions about the conversation data itself: your transcripts may contain proprietary code, credentials pasted into prompts, or client material, and the licence on the viewer says nothing about whether you may expose that content through a browser session. Read the LICENSE file in the repository for the actual terms.
Who should install it, and what to check on the first run
The clear fit is someone with an accumulated local history from Claude Code or Codex CLI who wants search, token statistics and a recent-edits view without writing a parser. The clear misfit is anyone whose assistant history is server-side only, or who needs a documented, versioned data interface to build on, because CCHV's contract is with file formats it does not control. On a first run, the thing to verify is detection: confirm the app finds your provider's real data directory, since the README lists defaults like ~/.claude/projects/ and ~/.codex/sessions/ that may not match a machine where paths were overridden, and check whether the override variables named in the provider table (CONTINUE_GLOBAL_DIR, INTERPRETER_HOME) apply to your setup. If you go the server route, start with cchv-server --serve on localhost, confirm authentication is enabled, and only then decide whether it belongs behind a reverse proxy. The project's own release history is the best signal of how much format churn you are signing up for.
Editorial conclusion
Adopt it if you have months of Claude Code or Codex CLI sessions and no way to search them, and start with a read-only pass: run the desktop build or cchv-server --serve against your existing ~/.claude/projects/ directory before trusting any export. Skip it if your history lives in a hosted product with no local files, or if you need a stable schema you can script against, because the provider parsers track file formats the upstream tools never promised to keep. Verify first that the app detects your provider's actual data directory on your machine, and if you expose the server, confirm authentication is on before binding it to anything but localhost.
Community notes