# claude-history: one TUI over Claude, Codex, Pi and OMP histories

> claude-history is a Rust terminal program that indexes the local session files of Claude Code, Codex, Pi and Oh My Pi, then lets you fuzzy-search, resume, fork and export the transcripts. It is narrow in scope by design: it reads local history and hands every agent action back to that agent's own CLI.

**raine/claude-history** — Fuzzy-search Claude Code conversation history

- Repository: https://github.com/raine/claude-history
- Stars: 521 · Forks: 58
- Language: Rust
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/raine-claude-history

## Four agent histories behind one searchable list

Coding agents keep their conversations, but they keep them in different places. Claude Code writes its own history, Codex stores rollouts under a home directory, and the Pi agent and Oh My Pi keep append-only JSONL session trees. After a few days of work in a project, the useful part of that history sits in files your editor cannot search well. claude-history is a Rust terminal program that reads those session stores, lists every conversation belonging to the current project, and lets you fuzzy-search across transcripts before opening one in a scrollable viewer. It is aimed at people who run coding agents daily and need to recover a decision, a command or a diff they discussed yesterday, not at people building agent infrastructure. The README describes it as a history browser, and the emphasis belongs on the browsing part: nothing here changes how an agent behaves, and nothing is sent anywhere.

## Field-aware scoring reaches past the visible preview

Search here is not a plain substring lookup. The project advertises fuzzy search across all conversations with field-aware relevance scoring, prefix matching, word boundary awareness and tool output indexing. The practical effect is that a query can match on a tool result that never appears in the one-line preview of a list entry, and a quoted exact match surfaces hidden context when the visible preview does not contain the hit. The list opens sorted by recency and narrows as you type, so relevance scoring decides what survives that filter. Lexical and semantic search run over the same corpus rather than over separate indexes, which means a fuzzy prefix hit and an embedding similarity hit compete in one list. That design has a cost: the ranking is opaque unless you know which field matched, so a session can jump to the top for a reason the interface never spells out.

## Installing the binary and opening your first session list

Installation is one script, and release archives also cover Apple Silicon macOS, Intel macOS and x86_64 Linux:

```sh
curl -fsSL https://raw.githubusercontent.com/raine/claude-history/main/scripts/install.sh | bash
```

On macOS and Linux a Homebrew tap is published:

```sh
brew install raine/claude-history/claude-history
```

If you would rather compile it, the crate is published under the same name:

```sh
cargo install claude-history
```

Then start it from the project directory whose history you care about:

```sh
$ claude-history
```

That opens the terminal UI listing the conversations found for that directory, sorted by recency, each row carrying a short preview. Typing searches across all transcripts. Two details matter for a first run. Discovery is anchored to the directory you launch from, so starting it in your home folder shows a different set of sessions than starting it inside a repository. And upgrades differ by install method: the built-in updater covers script and Cargo installs, while Homebrew installs must go through brew instead:

```sh
claude-history update
```

Expect a progress indicator during the first scan, since the semantic index has to be built before lexical and embedding results can be combined.

## Discovery rules differ for Pi, OMP and Codex

Session discovery is where most surprises live. The default Pi root is ~/.pi/agent/sessions, and Pi's own precedence decides the location: PI_CODING_AGENT_SESSION_DIR first, then sessionDir in .pi/settings.json for the current workspace, then sessionDir in the global settings.json, and finally the sessions directory under the Pi agent directory. PI_CODING_AGENT_DIR selects the agent directory and its global settings.json, with workspace settings overriding global ones. OMP adds profiles on top: the default root is ~/.omp/agent/sessions, named profiles sit under ~/.omp/profiles/<profile>/agent/sessions, and OMP_PROFILE falls back to PI_PROFILE when unset. Codex is the simplest of the three: its home is $CODEX_HOME, or ~/.codex when that variable is unset, and threads come from the sessions and archived_sessions directories, including compressed .jsonl.zst rollouts. When several sources contribute, rows carry fixed-width CC, Pi, OMP or CX labels, and a single-source list stays uncluttered. Those labels are the quickest way to tell which agent actually recorded a session.

## Resume and fork run through each agent's own CLI

Opening a transcript is only half the job, so the program ships agent protocol commands that act through each agent's native interface instead of editing session files by hand. Resume runs pi --session <path> in the session working directory, and fork runs pi --fork <path> in the current working directory. OMP behaves the same way through omp --resume <path> and omp --fork <path>. Renaming appends a native session_info record for Pi, while an OMP rename updates the title slot and appends a title_change audit record. Deletion is deliberately narrow: for Pi it removes only the selected JSONL file, and for OMP it removes that file together with its sibling artifact directory. The viewer itself offers vim-style scrolling, in-viewer search, stepping between messages and markdown rendering, and conversations or single messages can be exported or copied to the clipboard. Claude sessions accept configurable default resume arguments, and those defaults apply to Claude only, not to the other three agents. Resume and fork keybindings are configurable as well.

## Abandoned branches and compacted summaries stay out of the index

Some history is intentionally unreachable, and that is the clearest limitation in the design. For both Pi and OMP, the browser follows the active branch from the persisted leaf back to the root and excludes abandoned branches, so a fork you discarded earlier cannot be found through search. Pi control records, including compaction and branch summaries, model and thinking changes, labels and extension state, stay out of the dialogue and out of the search index; OMP excludes its title, mode, service tier, credential, reset and extension control records on the same basis. The consequence is that the summary of a long, compacted session does not match terms you would expect it to match, and you have to find it by opening the conversation itself. Image data in Pi conversations is represented by placeholders rather than indexed base64, so a term inside a screenshot is not searchable. Format support is bounded as well: Pi session versions 1 through 3 are supported in memory, and anything newer waits on a format update.

## Semantic search brings an embedded runtime with it

Embedding-based search has a dependency price, and the manifest makes it visible. The macOS release archives bundle ONNX Runtime so semantic search needs no separate runtime install there, but the Cargo manifest pulls in fastembed 6.0 and pins ort to the pre-release =2.0.0-rc.13, with a Cargo feature named release-dynamic-ort that switches ort to dynamic loading. Building from source therefore compiles an ONNX runtime as well as the application. The same manifest lists rusqlite with the bundled feature and zstd 0.13, which is how Codex's compressed rollouts and its sqlite state database are read, plus fst and memmap2 for index structures and icu_normalizer with compiled_data for text normalization. Indexing a large archive therefore has a real CPU and disk cost, and the README does not document a cache location or a way to trim the index. The repository is not archived, and the last push was on 2026-10-18, with v0.1.78 and v0.1.79 released on 2026-10-17 and v0.1.80 on 2026-10-18, so the interface can still shift between minor versions.

## Conclusion

claude-history suits developers who run Claude Code, Codex, Pi or Oh My Pi every day and lose track of what an agent decided last week, and it pays for itself when past transcripts matter more than the tooling around them. It is a poor fit for shared or server-side session stores, because it reads local JSONL files and drives the agents' own command line. Before adopting it, confirm that the session directory your agent writes to is one the discovery rules can reach, that your Pi sessions are still in format versions 1 through 3, and that you are willing to install a binary that embeds an ONNX runtime.

## FAQ

### Does claude-history only work with Claude Code sessions?

No. Despite the name it also handles Codex threads, Pi coding-agent sessions and Oh My Pi sessions, and list rows are tagged with fixed-width CC, Pi, OMP or CX labels when more than one source contributes conversations.

### How do I install claude-history on macOS and keep it updated?

A quick install script downloads a release, Homebrew installs the claude-history formula on macOS and Linux, and cargo install claude-history builds it from source. The macOS archives bundle ONNX Runtime so semantic search needs no separate runtime install. Script and Cargo installs update through the built-in update subcommand, while Homebrew installs should go through brew upgrade.

### Can claude-history search inside tool output and abandoned branches?

Tool output is indexed, so a match can surface context the list preview does not show. Abandoned branches are excluded on purpose for Pi and OMP sessions, and control records such as compaction summaries and model changes stay out of the dialogue and the search index.

## Sources

- [Issues](https://github.com/raine/claude-history/issues)
- [License: MIT](https://github.com/raine/claude-history/blob/main/LICENSE)
- [raine/claude-history on GitHub](https://github.com/raine/claude-history)
- [README](https://github.com/raine/claude-history/blob/main/README.md)
- [Releases](https://github.com/raine/claude-history/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/raine-claude-history