fast-resume CLI
Terminal search across Claude Code, Codex, OpenCode and other agent sessions, with a jump back into the right chat
- 190 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The index collects the text of all your agent conversations, which may hold private data
- Resume starts the original agent process in the session directory
Install
- Works in
Manual install
brew tap angristan/tap && brew install fast-resumeThe simplest route on macOS and Linux. The launch command is fr.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The index collects the text of all your agent conversations, which may hold private data
- Resume starts the original agent process in the session directory
This is third-party code. Review the repository files before installing.
What it does
The `fr` command builds one full-text index over the local history of coding agents. You can search by session title, directory, user messages and model replies. Tantivy-based search tolerates typos and ranks exact matches higher. Running it with no flags opens a Ratatui interface where arrow keys pick a session, `Ctrl+P` toggles the preview, `Ctrl+Y` copies the resume command and `Enter` hands control to the original agent. Filters work from the command line and inside the search box: `agent:`, `dir:` and `date:`, for example `fr -a codex -d backend "api error"`. `fr --list` prints results without the interface, `fr --stats` shows the index state and `fr --rebuild` rebuilds it. Agents get stable JSON: `fr --json --limit 10 "dir:backend authentication bug"` with pagination through `--offset`. `fr --agent-context` prints the bundled skill with rules for safe search and resume.
Who it is for. People who run dozens of sessions in Claude Code, Codex and OpenCode and lose the right conversation among titles in resume lists.
Good fit when
- An agent fixed a similar error a week ago and you need that session by the text of its reply
- There are many sessions across directories and the search must be limited by project and date
- Work spread across several agents and searching in one place is more convenient
- The agent itself has to find a past session and suggest a resume command without parsing a terminal table
- You want index statistics and a quick rebuild after a storage format change
Not a fit when
- The agent history lives on another machine: the index is built only from local files
- You want to browse history in a browser with diffs and metrics: fast-resume works in a terminal
- The agent is not in the supported list: the adapter list is fixed in the README
Example request
Use fast-resume to find the Codex session in the `backend` directory where we fixed an authentication bug in the last two weeks and show the resume commandLimitations
- Supported are Antigravity CLI, Claude Code, Codex, Copilot CLI, Copilot in VS Code, Crush, Cursor CLI, fx, Grok Build, Kimi Code, OpenCode, Pi and Vibe. Other agents are not indexed.
- The index lives in `~/.cache/fast-resume/tantivy_index` or under `$XDG_CACHE_HOME`. It holds the text of your conversations, which may contain private project data.
- Handing control over starts the agent process in the session directory. Turn on `--yolo` only deliberately.
- For stable JSON results the agent should call `fr` with a small `--limit` and read pages by `meta.next_offset`.
How to disable. Remove the program the way you installed it: `brew uninstall fast-resume`, `npm uninstall --global fast-resume` or `uv tool uninstall fast-resume`. The index lives in `~/.cache/fast-resume` and can be deleted by hand.
FAQ
How do I install fast-resume?
On macOS and Linux the simplest is `brew tap angristan/tap && brew install fast-resume`. `npm install --global fast-resume`, `uv tool install fast-resume` and Nix also work.
How do I let an agent use fast-resume itself?
Run `fr --agent-context`: it prints the bundled skill. The agent calls `fr --json` and reads the `sessions` and `meta` fields, so there is no table to parse.
Which filters does search have?
`agent:`, `dir:` and `date:`, for example `agent:claude date:<2d auth`. The same values are set with the `-a` and `-d` flags on the command line.
Where is the index stored and how do I reset it?
In `~/.cache/fast-resume/tantivy_index` or under `$XDG_CACHE_HOME`. Delete the directory and run `fr --rebuild`: the index is rebuilt from scratch.
What happens on Enter?
The program hands control to the original agent and resumes the selected session. The command can be copied with `Ctrl+Y` and run by hand.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill for searching past sessions: a full-text index of Claude Code, Codex, pi and Grok chats in one SQLite database
Local browsing, search and cost tracking for Claude Code, Codex and other agent sessions in one web UI
The /myoffice command opens a browser office showing what every agent on your machine is doing: thinking, waiting for you or done.
A terminal session manager for Claude Code, Cursor CLI, Kiro CLI and Codex: names, tags, projects, search and resume.
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
Voice control of Claude Code and Codex sessions on your machines: a small agent on each box links it to the pitupitu cloud.
README in short
The short README states the problem: agents can resume sessions but searching past ones is weak. A feature list, supported agents, install via Homebrew, Nix, npm and `uv` and a quick start with sample commands follow. A separate paragraph covers agent use through JSON, then links to the docs.