Stop Losing Your Coding Agent Sessions! fast-resume Is the Fix

You've been there. It's 2 AM. You're debugging a brutal authentication bug across three different AI coding agents. Claude Code helped you trace the JWT validation yesterday. Codex suggested that middleware fix last Tuesday. And somewhere—somewhere—Copilot CLI had the perfect regex for header parsing. But which session was it? Which agent? What even was the project directory?

Here's the dirty secret nobody talks about: coding agents are incredible at starting work, but terrible at helping you find work you've already done. Each tool lives in its own silo. Claude has its JSONL files buried in ~/.claude/. Codex scatters sessions across ~/.codex/. Copilot hides everything in VS Code's workspace storage. The built-in search? Title-only, if it exists at all. You're left cd-ing into random directories, running claude --resume with guessed UUIDs, praying you stumble onto the right conversation.

What if you could search across every coding agent session from a single terminal command? Full-text search through every message you and the LLM exchanged. Fuzzy matching so typos don't matter. A gorgeous fzf-style interface that shows previews, agent icons, and lets you hit Enter to resume instantly. No more archaeological digs through ~/.config. No more lost context.

That tool exists. It's called fast-resume, and it's about to become the most important command in your terminal.

What Is fast-resume?

fast-resume is an open-source command-line tool created by Stanislas Lange (angristan) that aggregates all your coding agent sessions into a single, blazing-fast searchable index. Born from the very real frustration of managing multiple AI assistants—Claude Code, Codex, GitHub Copilot, OpenCode, Vibe, Crush, and more—fast-resume eliminates the fragmentation that plagues modern AI-assisted development.

The project is written in Python^{↗ Bright Coding Blog} and distributed via PyPI and Homebrew, but its secret weapon is Tantivy: a Rust-powered full-text search engine (similar to Apache Lucene) that handles fuzzy queries over thousands of sessions in under 10 milliseconds. This isn't some toy script parsing JSON files—it's a production-grade search architecture with incremental updates, schema versioning, batched indexing, and parallel adapter execution.

Why is it trending now? Because 2025 is the year of coding agent proliferation. Developers aren't using an AI assistant—they're using five or six, each optimized for different tasks. Claude Code for complex refactoring. Codex for quick prototypes. Copilot for inline completions. The cognitive overhead of context-switching between these tools was becoming unbearable. fast-resume arrived at exactly the right moment, solving a problem that every power user felt but nobody had properly addressed.

The repository has gained significant traction on GitHub because it solves a universal pain point with elegant engineering. It's not just a convenience tool—it's a productivity multiplier that respects your time and your mental bandwidth.

Key Features That Make fast-resume Insane

Let's dissect what makes this tool technically impressive and practically indispensable:

Unified Full-Text Search Across All Agents Unlike native resume features that trap you in single-agent silos, fast-resume creates one search index spanning every supported tool. Search through actual conversation content—your prompts and the LLM's responses—not just session titles. That obscure middleware discussion from three weeks ago? Found in milliseconds.

Rust-Powered Performance with Tantivy The search backend is Tantivy, accessed via tantivy-py Python bindings. This gives you Lucene-quality inverted indexing with BM25 scoring, but compiled to native code. The result: fuzzy matching with edit distance 1, prefix queries, and boolean combinations all executing in single-digit milliseconds. The index lives in ~/.cache/fast-resume/tantivy_index and uses incremental updates to avoid re-parsing unchanged files.

Fuzzy Matching with Smart Ranking fast-resume implements hybrid search combining exact matches (boosted 5×) with fuzzy term queries. Type auth midleware and it finds "authentication middleware" because the fuzzy query tolerates typos while the exact match boost ensures precision when you nail the spelling.

Beautiful Terminal UI with Live Preview Built on Textual with Rich formatting, the interface features agent icons, color-coded results, a resizable preview pane with match highlighting, and vim-style keybindings. It's the kind of polish you expect from modern CLI tools, not a quick hack.

Direct Resume with Process Replacement When you select a session, fast-resume doesn't spawn a subprocess—it uses os.execvp() to replace itself entirely with the original agent's resume command. This means your shell history shows claude --resume abc123, not fr, and the agent inherits the correct working directory seamlessly.

Yolo Mode for Maximum Velocity For agents supporting auto-approve workflows, fast-resume detects or prompts for permission-bypassing flags. Codex and Vibe store their yolo state in session files and resume automatically. For Claude and Copilot CLI, an interactive modal lets you toggle dangerous mode per-session. Use fr --yolo to force it globally.

Update Notifications & Zero Configuration The tool checks for new versions automatically and works out of the box with sensible defaults. No config files to wrestle with.

Real-World Use Cases Where fast-resume Shines

The Multi-Agent Archaeologist

You're maintaining a legacy codebase and have used Claude Code for refactoring, Codex for test generation, and Copilot for inline fixes over three months. A regression appears in authentication. You remember discussing JWT libraries but not which agent or when. fr "jwt library comparison" surfaces the exact Claude session from 47 days ago, complete with the LLM's analysis of pyjwt vs jose.

The Context-Switching Consultant

You juggle six client projects, each with different tech stacks. Yesterday's Terraform debugging in ~/client-a/infra blends into today's Kubernetes troubleshooting in ~/client-b/k8s. fr -d client-a "state lock" instantly filters to that project's sessions, showing the Codex conversation where you resolved the DynamoDB locking issue.

The Permission-Bypassing Power User

You're in a tight iteration loop with Codex, repeatedly testing API endpoints. Normally you'd type --dangerously-bypass-approvals-and-sandbox every resume. fast-resume detects your original yolo session and automatically appends the flag. Or use fr --yolo to never think about it again.

The Team Knowledge Archaeologist

Your teammate solved a bizarre Nginx configuration issue through Claude Code last month. They shared the solution in Slack, but not the session ID. With fast-resume's statistics dashboard (fr --stats), you see all sessions in ~/project-nginx/ and search proxy_pass websocket to find their exact conversation, learning the full context—not just the final answer.

Step-by-Step Installation & Setup Guide

Prerequisites

For the optimal experience, Ghostty is recommended. Other terminals may struggle with interactive features and image rendering.

Method 1: Homebrew (Recommended)

# Add the custom tap and install
brew tap angristan/tap
brew install fast-resume

# Verify installation
fr --version

Method 2: uv/PyPI (Flexible)

# Run without installing (perfect for trying it out)
uvx --from fast-resume fr

# Or install permanently as a tool
uv tool install fast-resume

# Now available globally
fr

Method 3: Development Installation

# Clone the repository
git clone https://github.com/angristan/fast-resume.git
cd fast-resume

# Sync dependencies with uv
uv sync

# Run locally
uv run fr

# Install pre-commit hooks for contributing
uv run pre-commit install

First Launch & Index Building

On first run, fast-resume automatically scans all known agent directories and builds its search index. This takes approximately 2 seconds for ~500 sessions. Subsequent launches with no changes complete in ~50ms thanks to incremental mtime comparison.

# Force rebuild if something seems off
fr --rebuild

# Clear everything and start fresh
rm -rf ~/.cache/fast-resume/
fr --rebuild

REAL Code Examples from fast-resume

Let's examine actual implementation patterns from the repository, explaining the engineering decisions that make this tool exceptional.

Example 1: Hybrid Search Implementation

This is the core of fast-resume's search intelligence—combining exact and fuzzy matching for optimal results:

# From src/fast_resume/index.py - the search engine core

# Exact match query using BM25 scoring on title and content fields
exact_query = index.parse_query(query, ["title", "content"])
# Boost exact matches 5x so precise queries rank highest
boosted_exact = tantivy.Query.boost_query(exact_query, 5.0)

# Build fuzzy query for typo tolerance (edit distance 1)
fuzzy_terms = []
for term in query.split():
    # Fuzzy match in title with prefix matching enabled
    fuzzy_title = tantivy.Query.fuzzy_term_query(
        schema, "title", term, distance=1, prefix=True
    )
    # Fuzzy match in full conversation content
    fuzzy_content = tantivy.Query.fuzzy_term_query(
        schema, "content", term, distance=1, prefix=True
    )
    fuzzy_terms.extend([fuzzy_title, fuzzy_content])

# Combine all fuzzy terms with OR logic
fuzzy_query = tantivy.Query.boolean_query([
    (tantivy.Occur.Should, t) for t in fuzzy_terms
])

# Final query: exact OR fuzzy (exact scores higher due to boost)
final_query = tantivy.Query.boolean_query([
    (tantivy.Occur.Should, boosted_exact),
    (tantivy.Occur.Should, fuzzy_query),
])

Why this matters: The 5× boost on exact matches ensures that typing "authentication" correctly finds that exact term first. But if you typo "auth midleware," the fuzzy query with edit distance 1 still catches "authentication middleware" because Tantivy allows one character substitution, deletion, or insertion. Prefix matching means "auth" also matches "authentication" without the full term. This hybrid approach eliminates the frustrating precision-recall tradeoff that plagues simple search implementations.

Example 2: Incremental Indexing with Progress Streaming

This pattern shows how fast-resume avoids re-parsing everything on every launch:

# From src/fast_resume/search.py - SessionSearch orchestration

def handle_session(session):
    """Callback invoked by each adapter as sessions are parsed.
    
    Buffers sessions for efficient batch commits to Tantivy,
    then triggers TUI progress updates for responsive feel.
    """
    pending_sessions.append(session)
    # Commit in batches to balance throughput vs. latency
    if len(pending_sessions) >= BATCH_SIZE:
        self._index.update_sessions(pending_sessions)  # Atomic batch commit
        pending_sessions.clear()
        on_progress()  # Notify TUI to render newly available sessions

# Adapters run in parallel via ThreadPoolExecutor
# Each calls on_session as soon as a session is parsed
adapter.find_sessions_incremental(known_mtimes, on_session=handle_session)

The engineering insight: Instead of waiting for all adapters to finish (which could take seconds), sessions appear in the TUI as they're parsed. OpenCode's adapter even uses parallel file I/O and processes smaller sessions first for faster initial results. The known_mtimes dictionary from the existing Tantivy index enables incremental updates—only files with current_mtime > known_mtime + 0.001 get re-parsed. This makes warm starts nearly instantaneous.

Example 3: Process Replacement for Seamless Resume

This is the handoff magic—how fast-resume disappears completely when you resume:

# From src/fast_resume/cli.py - after TUI selection

# run_tui returns the exact resume command and original directory
resume_cmd, resume_dir = run_tui(query=query, agent_filter=agent)

if resume_cmd:
    # 1. Switch to the session's original working directory
    #    Critical: agents expect to resume where they started
    os.chdir(resume_dir)
    
    # 2. Replace THIS Python process with the agent CLI
    #    No subprocess overhead. No "fr" in shell history.
    #    The agent inherits file descriptors and environment.
    os.execvp(resume_cmd[0], resume_cmd)
    # Never returns - this process is now claude/codex/etc.

Why os.execvp() instead of subprocess.run()? Three reasons. First, zero overhead—no Python process lingering in memory. Second, shell history cleanliness: your ~/.bash_history shows claude --resume abc123, making future manual resumption trivial. Third, proper signal handling and TTY inheritance: the agent believes it was launched directly by you, not wrapped, which matters for interactive features.

Example 4: Schema Versioning for Robust Upgrades

A subtle but critical reliability feature:

# From src/fast_resume/index.py - index initialization

# Check if existing index matches current code's schema
schema_version_path = index_dir / ".schema_version"
if schema_version_path.exists():
    stored_version = schema_version_path.read_text().strip()
else:
    stored_version = None

if stored_version != SCHEMA_VERSION:
    # Schema mismatch: incompatible index format
    # Delete and rebuild to prevent deserialization crashes
    shutil.rmtree(index_dir)
    index_dir.mkdir(parents=True, exist_ok=True)
    schema_version_path.write_text(SCHEMA_VERSION)
    # Proceed with full reindex...

The defensive programming: When fast-resume updates its Session dataclass or Tantivy field configuration, old indexes would crash on load. Rather than failing mysteriously, it detects the version mismatch and rebuilds automatically. Users experience a one-time slow start, not a broken tool.

Advanced Usage & Best Practices

Master the Keyword Syntax: The search box isn't just raw text. Use agent:claude date:<1d "api error" for precise filtering. Exclude agents with -agent:vibe, combine multiple with agent:claude,codex, or filter directories with dir:backend,!test. Tab-complete agent:cl to agent:claude.

Preview Pane Navigation: Hit Ctrl+\`` to toggle the preview, +/-` to resize. The preview jumps to match position with ~100 characters of context, so you immediately see why a session matched.

Clipboard Integration: Press c to copy the full resume command. Paste into documentation, share with teammates, or save for automation.

Statistics for Self-Awareness: Run fr --stats weekly. The activity heatmaps reveal your peak coding hours and which projects consume most AI assistance. Spot agents you barely use—maybe time to drop that subscription?

Yolo Mode Safely: Use fr --yolo only in trusted, version-controlled environments. The interactive modal (Tab to toggle) is safer for mixed contexts. Remember: Codex and Vibe auto-detect yolo from session metadata; Claude and Copilot CLI require explicit confirmation.

fast-resume vs. Alternatives: Why It Wins

The native resume features are fine for recency—"what was I just doing?" For discovery across time, agents, and projects, they're hopelessly inadequate. Raw grep works but requires knowing where to look and can't rank results. fast-resume is the only solution that combines comprehensiveness, speed, and usability.

FAQ: What Developers Ask About fast-resume

Does fast-resume store my conversations in the cloud? No. Everything stays local. The Tantivy index lives in ~/.cache/fast-resume/, and session data is read from your existing agent directories. No network calls, no telemetry, no external servers.

Which coding agents are supported? Currently Claude Code, Codex, GitHub Copilot (CLI and VS Code), OpenCode, Vibe, and Crush. The adapter architecture makes adding new agents straightforward—contributions welcome.

How much disk space does the index use? Roughly 1-2% of your raw session data. The README shows 15.5 MB indexing 751 sessions with 13,799 messages. The index excludes tool outputs and focuses on actual conversation text.

Can I use fast-resume without the TUI? Yes. fr --no-tui outputs to stdout, and fr --list shows sessions without offering to resume. Perfect for scripting and CI pipelines.

What happens if an agent updates its session format? The adapter system isolates format changes. If Claude Code changes its JSONL schema, only src/fast_resume/adapters/claude.py needs updating. The core search and TUI remain untouched.

Is there a Windows version? The tool is Python-based and should work cross-platform, though Ghostty terminal (recommended) is currently macOS/Linux focused. Community Windows testing and contributions are encouraged.

How do I contribute or report bugs? Visit https://github.com/angristan/fast-resume. The project uses uv for dependency management, pytest for testing, and ruff for linting. Pre-commit hooks ensure code quality.

Conclusion: Your AI Coding Memory, Finally Organized

The proliferation of AI coding agents in 2025 has created a hidden productivity crisis: we're generating more valuable technical conversation than ever, but we've had no way to find it again. fast-resume solves this with engineering elegance—Rust-powered search, incremental indexing, seamless process handoff, and a gorgeous terminal interface that makes archaeology feel like teleportation.

Stanislas Lange identified a universal pain point and built the definitive solution. Whether you're juggling three agents or seven, working solo or sharing context with teammates, fast-resume transforms scattered session files into a searchable second brain for your AI-assisted development.

Stop losing your best coding conversations to the void. Install fast-resume today, run fr, and experience what it feels like when every insight you've ever generated with an AI assistant is one fuzzy search away.

👉 Get fast-resume on GitHub — star it, install it, never lose a session again.