cct — Search and browse your Claude Code sessions

Claude Code sessions are ephemeral. When you need context from yesterday's debugging session or last week's architecture decision, there's no easy way to find it. cct makes your session history searchable — for you and for Claude itself.

Requires Claude Code. macOS and Linux.

Install

brew install andyhtran/tap/cct

To update:

brew update && brew upgrade cct

Build from source

git clone https://github.com/andyhtran/cct.git
cd cct && go build -o cct ./cmd/cct

Finding past sessions

Search across all your conversations:

cct search "database migration"       # Find sessions mentioning a topic
cct search "auth bug" -p backend      # Filter to a specific project

List recent sessions:

cct                     # Quick view: 5 most recent
cct list -p myproject   # Filter by project name
cct list -a             # Show all sessions

Getting full context

View a session in your terminal:

cct view <id>           # Interactive TUI viewer

Export to markdown:

cct export <id>           # Truncated output
cct export <id> --full    # Complete conversation
cct export <id> --render  # Syntax-highlighted terminal output

Why not claude --resume? There are known issues where resumed sessions don't load full context (#15837, #22107). Use cct view or cct export when you need the complete conversation.

Resuming work

cct resume <id>         # cd to project dir and run claude --resume

Use with Claude Code agents

cct skill install ships a Claude Code discovery stub that the harness auto-loads when you reference past sessions. The full guidance is embedded in the cct binary and updates with each brew upgrade cct — no manual file copying.

cct skill install       # creates/refreshes ~/.claude/skills/cct/SKILL.md
cct skill status        # check install/ownership/nudge state
cct skill uninstall     # remove the managed stub
cct skill nudge off     # silence the install prompt
cct skills get core     # print the runtime guidance

Then prompt naturally:

use cct to find sessions where we debugged the auth issue

The stub preserves auto-discovery; cct skills get core supplies canonical workflows (search→export, list→info, JSON+jq pipelines) and anti-patterns so agents prefer cct over grep ~/.claude/projects/. Until installed, cct prints a one-line install hint to stderr (rate-limited to once per 24h); run cct skill nudge off to silence.

Preserving session history

Claude Code occasionally wipes session files in ~/.claude/projects/ — see upstream issues #41458, #23710, and #20992. cct backup sweep hardlinks your ~/.claude/projects/**/*.jsonl files into ~/.cct/data/backup/ so session history survives those cleanups. Hardlinks mean the backup costs near-zero disk (the live file and the backup point at the same inode), and drift is detected if the live file is replaced.

cct backup status    # Per-session drift report (backed-up / drifted / orphaned)
cct backup sweep     # Hardlink every session file into the backup tree
cct backup restore <id> --dry-run
cct backup restore <id>  # Copy a backup back to ~/.claude/projects/

cct never modifies ~/.claude/settings.json. Backup is a manual command — automate it with cron or launchd if you want hands-off.

Backups are per-machine — they track local inodes and absolute paths. Don't sync ~/.cct/data/backup/ across machines.

Looking up Claude Code features

cct changelog mirrors the upstream CHANGELOG.md locally (cached under ~/.cct/cache/ for 6h) and makes it searchable:

cct changelog                              # Latest release
cct changelog --search "disable|opt.?out"  # Grep for ways to turn things off
cct changelog --search "plan.*name"        # Find mentions of a specific feature
cct changelog --since 2.1.100 --all        # Every change in a version window
cct changelog --refresh                    # Force re-fetch from GitHub

Useful when you want to answer "did Claude Code add a flag for X?" or "what changed between versions?" without leaving the terminal.

Other commands

cct info <id>    # Session metadata: project, branch, timestamps
cct stats        # Usage statistics across all projects

Run cct --help for additional commands.

Storage

cct stores its own files under ~/.cct/: cache/ for the search index and changelog cache, data/ for durable backups, and state/ for small CLI state. Set CCT_HOME to override this for isolated runs. Run cct paths --json to inspect effective paths. Legacy ~/.cache/cct data is migrated on normal cct invocations.

JSON output

Data commands support --json for scripting:

cct search "bug" --json | jq -r '.[].short_id'

How it works

cct reads session data from ~/.claude/projects/ (JSONL files). All operations are read-only.

The Claude Code data format is undocumented and may change between versions.

License

MIT