feat: add tb-session CLI for Claude Code session search

[dafilipaj]

Summary

New tb-session CLI tool that indexes and full-text searches Claude Code sessions via SQLite FTS5. Joins the cli-toolbox workspace alongside tb-prod, tb-sem, tb-bug, and tb-lf.

Commands

Command	Description
search	FTS5 full-text search with BM25 ranking, snippets, and filters (--branch, --pr, --project, --after/before)
list	Browse sessions by metadata with pagination
show	Session detail with conversation preview
resume	Resume a past session — opens a new terminal tab (iTerm/Terminal.app) since Claude sessions can't nest
index	Explicit index rebuild with stats
doctor	Verify setup health (Claude home, projects dir, DB, FTS5, claude binary)
cache-clear	Delete index for clean rebuild
prime	AI-optimized context dump for Claude skill injection
config	Show/init config at ~/.config/tb-session/config.toml
skill install	Install SKILL.md to ~/.claude/skills/tb-session/

Key features beyond basic search

• Worktree-aware scoping — list and search automatically include sessions from all git worktrees of the same repo, not just the exact cwd
• Smart resume — accepts session IDs, UUID prefixes (any length), or name/search terms that match session summary/first prompt
• New terminal tab for resume — when invoked from within Claude Code (non-TTY), automatically opens a new iTerm/Terminal.app tab, cd's into the original project directory, and runs claude --resume
• --pr filter — tb-session search --pr 557 finds sessions mentioning a PR by number or URL
• FTS5 query sanitization — URLs, colons, and other special characters work safely as search terms
• Versioned sessions-index.json — correctly parses Claude Code's {version, entries} format for fast metadata loading

Architecture

• SQLite FTS5 database at ~/.cache/tb-session/index.db
• Lazy indexing with 1h TTL — only re-parses changed/new JSONL files (mtime-based)
• Synchronous main (no tokio) — all I/O is local files + SQLite
• Smallest binary in the toolbox (3.6MB vs 8-12MB) — no reqwest/TLS dependency
• Custom error enum (no define_error! since that requires reqwest)
• osascript injection prevention — commands passed via env var, not string interpolation
• macOS-only guard on terminal tab spawning with helpful error on other platforms

Resume: why a new tab?

claude --resume starts a new interactive Claude Code session. This can't run inside an existing session — exec() would kill the current conversation. When tb-session resume detects it's running inside Claude (stdin is not a TTY), it opens a new terminal tab via osascript instead. The tab automatically:

1. cd's into the session's original project directory (if different from cwd)
2. Runs claude --resume <full-session-id> with the resolved UUID

When run from a regular terminal, it exec's directly as expected.

Installation

# From source (recommended during development)
cargo install --path crates/tb-session

# Install the Claude Code skill (teaches Claude to use tb-session)
tb-session skill install

# Verify setup
tb-session doctor

After installing, rebuild your index:

tb-session index --all-projects

Usage examples

Terminal usage

# Search sessions by content
tb-session search "authentication middleware"
tb-session search "budget calculation" --all-projects
tb-session search "refactor" --branch feature/auth

# Search by PR number
tb-session search --pr 557
tb-session search --pr 557 --all-projects

# Search by PR URL
tb-session search --pr https://github.com/productiveio/ai-agent/pull/557

# List recent sessions
tb-session list
tb-session list --all-projects --limit 20
tb-session list --branch main --after 2026-03-01

# Show session details
tb-session show bcb7ffed
tb-session show bcb7ff   # prefix match

# Resume by UUID (prefix or full)
tb-session resume bcb7ffed
tb-session resume 27b0337

# Resume by name/summary search
tb-session resume "auth refactor"
tb-session resume "PR review"

# JSON output for scripting
tb-session search "deploy" --json
tb-session list --json | jq '.[0].session_id'

Prompts that trigger Claude to use tb-session

When the skill is installed, these prompts make Claude reach for tb-session automatically:

> resume the session where we reviewed PR #557
> find the conversation about budgeting calculations
> show me the session where we debugged the auth middleware
> which sessions touched the frontend repo this week?
> resume my last session about deploy scripts
> find sessions mentioning the billing migration

Claude will run tb-session search, pick the right session, and tb-session resume it — opening a new terminal tab with the session.

Test plan

• 45 unit tests pass (schema, scanner, parser, builder, search, resume, git)
• 0 clippy warnings
• Tested with real data: 285+ sessions indexed across 10+ projects
• Search returns ranked results with snippets
• JSON output is structured and token-efficient
• Resume opens new iTerm tab with correct project directory
• Worktree-aware scoping includes sessions from linked worktrees
• --pr filter finds sessions by PR number and URL
• FTS5 sanitization handles URLs without "column not recognized" errors
• Empty search query returns clear error
• Short UUID prefixes (< 8 chars) resolve correctly
• Manual: tb-session doctor
• Manual: tb-session prime

Workspace changes

• Cargo.toml: added modern_sqlite to rusqlite features, added tb-session workspace dep
• scripts/install.sh: added tb-session to ALL_TOOLS
• scripts/bump.sh: added tb-session to VALID_TOOLS

Post-merge TODO

• Update SKILL.md description with stronger trigger keywords so Claude automatically reaches for tb-session on "resume session" prompts (currently Claude interprets "resume the session" as "continue the work" instead of using tb-session resume)
• Add tb-session to the work project CLAUDE.md CLI Toolbox section with explicit instructions to prefer it over manual JSONL searching
• Run tb-session skill install to deploy updated skill

🤖 Generated with Claude Code

[trogulja]

LGTM with one inline note on shell_escape.

Make sure to resolve the merge conflicts on Cargo.toml, scripts/bump.sh, and scripts/install.sh before merging — both tb-devctl and tb-session need to be in those lists.

[trogulja]

Security: shell_escape only triggers quoting for whitespace, ', ", and \. Shell metacharacters like $, backtick, ;, &, | pass through unquoted. Since the result is executed as a shell command by Terminal.app/iTerm via do script, a project path containing e.g. $(malicious) would trigger command substitution.

Fix: always single-quote unconditionally — the inner ' → '\'' replacement already handles embedded quotes:

fn shell_escape(s: &str) -> String {
    if s.is_empty() {
        return s.to_string();
    }
    format!("'{}'", s.replace('\'', "'\\''"))
}

[dafilipaj]

Fixed in 39b33cc — shell_escape now always single-quotes unconditionally. Added test cases for $(), backtick, ;, &, and |.