ccs

A TUI and CLI tool for searching and browsing Claude Code and Claude Desktop session history.

Built with Rust using ratatui and ripgrep.

Features

• Recent sessions on startup — shows your most recent sessions with first user message as summary when the TUI launches
• Full-text search across all Claude Code CLI and Claude Desktop sessions
• Regex search mode (toggle with Ctrl+R)
• Session grouping — results grouped by session with timestamps and project context
• Tree view — visualize conversation branches, forks, and context compactions (Ctrl+B)
• Session resume — press Enter to resume any session directly from search results or the recent sessions list
• Async search — non-blocking background search with debounce
• CLI mode — search and list subcommands with JSONL output for scripting
• Cross-platform — supports both Claude Code CLI (~/.claude/projects) and Claude Desktop sessions

Installation

Homebrew (macOS/Linux)

brew install materkey/ccs/ccs

Shell installer (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/materkey/ccfullsearch/releases/latest/download/ccfullsearch-installer.sh | sh

Cargo

cargo install ccfullsearch --locked

Cargo binstall

cargo binstall ccfullsearch

Requirements

ripgrep (rg) must be installed and available in PATH. The Homebrew formula installs it automatically.

Architecture

src/
├── lib.rs              # Crate root — re-exports all modules
├── main.rs             # CLI entry point (clap) + TUI event loop
├── cli.rs              # Non-interactive search/list commands (JSONL output)
├── session.rs          # Shared JSONL parsing primitives (timestamps, UUIDs, sources)
├── recent.rs           # Recent sessions: parallel scanning, summary extraction, RecentSession struct
├── search/             # Ripgrep integration, message parsing, result grouping
├── tree/               # Session DAG parsing, branch detection, flattened tree rows
├── resume/
│   ├── path_codec.rs   # Claude path encoding/decoding + filesystem walking
│   ├── fork.rs         # Branch chain detection + fork file creation
│   └── launcher.rs     # Process launching (exec on Unix, spawn on Windows)
└── tui/
    ├── state.rs         # App struct, constructor, input/cursor methods, tick loop
    ├── search_mode.rs   # Search navigation, enter, toggle, search orchestration
    ├── tree_mode.rs     # Tree mode enter/exit, navigation, file lookup
    ├── render_search.rs # Search & preview rendering (+ recent sessions empty state)
    └── render_tree.rs   # Tree mode rendering

tests/
├── fixtures/           # Representative JSONL session files
├── cli_search.rs       # Integration tests for `ccs search`
├── cli_list.rs         # Integration tests for `ccs list`
├── tree_parsing.rs     # Tree parsing via library API
├── resume_resolution.rs # Resume session resolution tests
└── render_snapshots.rs # TUI render state verification

Testing

# Run all tests
cargo test

# Quality checks (same as CI)
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Usage

Interactive TUI

# Launch — shows recent sessions on startup, start typing to search
ccs

# Open tree view for a specific session
ccs --tree <session-id-or-path>

CLI mode

# Search sessions (outputs JSONL)
ccs search "docker build" --limit 10

# Search with regex
ccs search "OOM|OutOfMemory" --regex

# List all sessions sorted by last activity
ccs list --limit 20

Keybindings

Recent sessions (empty input)

Search mode

Tree mode

Claude Code Skill

The repo includes a Claude Code skill so Claude can search your sessions automatically. To install:

cp -r skill ~/.claude/skills/claude-session-search

Then Claude will use ccs when you ask things like "find where we discussed docker" or "list my recent sessions".

Releasing

1. Bump version in Cargo.toml
2. Commit and push to main
3. Publish to crates.io: cargo publish
4. Tag and push: git tag v<VERSION> && git push origin v<VERSION>

The tag push triggers cargo-dist which:

• Builds binaries for macOS (arm64/x86_64) and Linux (gnu/musl, arm64/x86_64)
• Creates tar.gz archives with SHA256 checksums
• Publishes a GitHub Release with all artifacts
• Updates the Homebrew formula in materkey/homebrew-ccs

How it works

1. Searches JSONL session files using ripgrep for speed
2. Parses matched lines as Claude session messages (user, assistant, tool calls)
3. Groups results by session with metadata (project name, timestamps)
4. Tree view parses the full session DAG to show conversation branches and the latest chain