fast-resume
Search and resume conversations across Claude Code, Codex, Pi, and more, all from one terminal UI.
Coding agents can resume previous sessions, but searching those sessions is often limited or title-only. fast-resume builds a single full-text index over your local agent history so you can find a prompt, response, project, or session and jump straight back in.
https://github.com/user-attachments/assets/60f6e128-2ae4-431d-8a87-097f600b6d04
Highlights
- Search titles, directories, user messages, and assistant responses across every supported agent.
- Find imperfect matches with typo-tolerant Tantivy search and exact-match ranking.
- Filter by agent, directory, and date from the command line or directly in the search box.
- Preview conversations, copy resume commands, or hand off directly to the original agent.
- Start immediately from the existing index while changed sessions refresh in the background.
- Use agent artwork, mouse controls, responsive filters, and compact layouts in the Ratatui TUI.
Supported agents
Antigravity CLI, Claude Code, Codex, Copilot CLI, Copilot in VS Code, Crush, Cursor CLI, Grok Build, Kimi Code, OpenCode, Pi, and Vibe. See how it works for storage formats and resume behavior.
Install
Homebrew is the simplest option on macOS and Linux:
brew tap angristan/tap
brew install fast-resume
Nix users can run directly from the source package:
nix run github:angristan/fast-resume
You can also install with npm or a binary wheel with uv:
npm install --global fast-resume
# or
uv tool install fast-resume
See the installation guide for Nix, npm, uvx, Cargo, supported platforms, and terminal recommendations.
Quick start
# Search all sessions interactively
fr
# Start with a query or filters
fr "authentication bug"
fr -a codex -d backend "api error"
# Search without opening the TUI
fr --list "agent:claude date:<2d auth"
# Inspect or rebuild the local index
fr --stats
fr --rebuild
Inside the TUI, use the arrow keys to select a session and press Enter to resume it. Tab completes filters or cycles agents, Ctrl+P toggles the preview, and Ctrl+Y copies the resume command.
Agent usage
Coding agents can use the stable JSON output instead of parsing the human table:
fr --json --limit 10 "dir:backend authentication bug"
fr --json --limit 10 --offset 10 "dir:backend authentication bug"
Run fr --agent-context to print the bundled Agent Skill with safe search, pagination, and resume guidance.
Documentation
- Installation — packages, platforms, terminals, and upgrades
- Usage — search syntax, CLI options, keybindings, yolo mode, and statistics
- How it works — adapters, indexing, search, refresh safety, and resume handoff
- Development — local setup, validation, project layout, and release packaging
Configuration
No configuration is required. The Tantivy index follows the XDG Base Directory specification. It lives at $XDG_CACHE_HOME/fast-resume/tantivy_index when XDG_CACHE_HOME is an absolute path, or at ~/.cache/fast-resume/tantivy_index by default. It is rebuilt automatically when its schema changes.
To reset it manually:
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/fast-resume"
fr --rebuild
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for fast-resume 2.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| fast_resume-2.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| fast_resume-2.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| fast_resume-2.12.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| fast_resume-2.12.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 20.8 MB
Release files / fast_resume-2.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | fast_resume-2.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.4 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
d981b25a012765507c2e0f3d7b3fac84244e7d8165f3d2b7564c36098d8a8354
|
|
BLAKE2b-256 checksum How to use checksums |
34bde9e90a62dc5b0484198684c0402beb877b175fa0562d47ee8461fe1900a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / fast_resume-2.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | fast_resume-2.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
d4c8e9f12a685885d074b277004cce9b12385f4710124ae465ef0aa21bbf325d
|
|
BLAKE2b-256 checksum How to use checksums |
424f7aebd9e24a7b9cb7b5d27e0dc46354c2808de6f8323f77b40037a9de04b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / fast_resume-2.12.0-py3-none-macosx_11_0_arm64.whl
| Download URL | fast_resume-2.12.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.0 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
911cff00221a8b600dce414b85936f297c01b77f8e9610683f033098a10706ab
|
|
BLAKE2b-256 checksum How to use checksums |
8c40ad0b1ff055fa696cee7033d689d7972e714d489c5def6c4b452d5e7795ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / fast_resume-2.12.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | fast_resume-2.12.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
6124be1cfca6f5f5ffacbff820ae10f764aeeae0666567c1f4ad67e8ba684c37
|
|
BLAKE2b-256 checksum How to use checksums |
a7ab370856934f2ce0cb05fc5a1b7fb14af96f9831c2f2b809680cfddb3b3f00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
