claude-tracker-suite

Claude Session Management Suite

Search, browse, monitor, and manage Claude Code session history across all projects.

Tools Overview

| Tool | Purpose | |------|---------| | claude-tracker-search | Search sessions by keyword or ID prefix (standalone script) | | open-sessions.js | List top N sessions, open selected in cmux tabs/splits | | claude-tracker-resume | Find and resume crashed/inactive sessions | | claude-tracker-alive | Check which sessions have running processes | | claude-tracker-watch | Daemon: auto-summarize new sessions, update active-projects.md | | claude-tracker | List recent sessions with status badges (standalone script) | | new-session.sh | Start a new session in Ghostty/VSCode/Cursor, with optional prompt or headless mode | | resume-session.sh | Open a session in a cmux tab (optionally open project in VS Code/Cursor) | | detect-projects.js | Scan sessions to find all projects, check CLAUDE.md coverage | | bootstrap-claude-setup.js | Generate complete ~/.claude/ config for new machine | | update-active-projects.py | Regenerate active-projects.md with enriched session data | | checkpoint-session.js | Create/query named bookmarks within sessions | | quote-session.js | Capture/search notable phrases with FTS5 | | tag-session.js | Manual session tagging with provenance | | claude-tracker-recent | Show last N sessions with full metadata (title, tags, summary, cost, model) |

Standalone Scripts

Commands delegate to standalone Node.js scripts (avoids shell escaping issues with inline node -e):

| Script | Called By | Purpose | |--------|-----------|---------| | scripts/search-sessions.js | /claude-tracker-search | Keyword search or --id prefix lookup across all sessions | | scripts/open-sessions.js | Direct invocation | List top N sessions, open in cmux tabs/splits with confirmation | | scripts/list-sessions.js | /claude-tracker | List recent sessions with status badges | | scripts/new-session.sh | /spawn | Start new interactive or prompt-driven session in Ghostty/VSCode/Cursor or headless | | scripts/resume-session.sh | Direct invocation | Open session in cmux tab, optionally open project in VS Code/Cursor | | scripts/detect-projects.js | Direct invocation | Project discovery and CLAUDE.md scaffolding | | scripts/bootstrap-claude-setup.js | Direct invocation | New machine setup generator | | scripts/checkpoint-session.js | /checkpoint, /checkpoint-list | Create and query session checkpoints | | scripts/quote-session.js | /quote, /quote-search | Capture and search tagged phrases via FTS5 | | scripts/tag-session.js | /tag | Manual session tagging with provenance | | scripts/recent-sessions.js | /claude-tracker-recent | Last N sessions with title, tags, summary, model, cost | | ~/.claude/scripts/ghostty-resume.sh | Direct invocation | Open session in a new Ghostty tab |

All scripts use ~/.claude/lib/tracker-utils.js for shared utilities (path decoding, session parsing, git remote detection) and ~/.claude/lib/tracker-db.js for SQLite access (better-sqlite3, WAL mode).

Quick Start

# Search by topic
claude-tracker-search "kothar mac mini"

# Lookup by session ID prefix (exact directory from JSONL ground truth)
node ~/.claude/skills/claude-tracker-suite/scripts/search-sessions.js --id d7b8f4dd

# Search by session name/slug only (fast — no JSONL body scan)
claude-tracker-search "thera" --name

# List top 10 sessions, open selected in cmux tabs
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js

# Open top 5 as vertical splits
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --limit 5 --split right

# Check what's alive
claude-tracker-alive

# Resume crashed sessions in tmux
claude-tracker-resume --tmux

# Start auto-summarize daemon
claude-tracker-watch --daemon

Search

claude-tracker-search "$ARGUMENTS"

Search targets (weighted ranking): Summary (3x), First prompt (2x), Project name (1x), Git branch (1x).

| Flag | Description | |------|-------------| | --limit <n> | Max results (default: 20) | | --id <prefix> | Lookup by session ID prefix (8+ chars) | | --project <name> | Filter by project name (substring) | | --since <duration> | Recent only: 7d, 24h, 30m, 2w | | --json | Machine-readable JSON output | | --name | Search only session names, slugs, summaries—skips JSONL body scan (fast) | | --fzf | Interactive selection via fzf (outputs resume command) |

Resume Crashed Sessions

claude-tracker-resume                    # List crashed sessions with resume commands
claude-tracker-resume --tmux             # Resume all in tmux windows
claude-tracker-resume --zsh              # Resume all in Terminal.app tabs (macOS)
claude-tracker-resume --all              # Include non-VS Code sessions
claude-tracker-resume --dry-run          # Preview without acting

Smart fallback: if --resume fails on an expired session, automatically starts a fresh session in that project directory. Sessions older than 7 days show a STALE badge.

Alive Detection

Check which sessions have running Claude processes:

claude-tracker-alive                     # Running + stale sessions overview
claude-tracker-alive --running           # Only sessions with active processes
claude-tracker-alive --stale             # Only sessions with no process
claude-tracker-alive --json              # Machine-readable output

Cross-references running claude PIDs (via pgrep + lsof) against recent session files. Sessions >3 days without a process show an OLD badge.

Auto-Summarize Daemon

Watch for new sessions and auto-populate summary cache:

claude-tracker-watch --status            # Check if daemon is running
claude-tracker-watch --daemon            # Start in background
claude-tracker-watch --stop              # Stop running daemon
claude-tracker-watch --verbose           # Foreground with debug output

The daemon watches ~/.claude/projects/*/sessions-index.json for changes. When new sessions appear, it caches summaries from Claude Code metadata and regenerates active-projects.md. See references/daemon-setup.md for launchd plist and lifecycle details.

Recent Sessions (Full Metadata)

claude-tracker-recent                          # Last 10 sessions with full metadata
claude-tracker-recent --limit 20               # Last 20 sessions
claude-tracker-recent --json                   # Machine-readable JSON output
claude-tracker-recent --project myapp          # Filter by project
claude-tracker-recent --model opus             # Filter by model
claude-tracker-recent --since 7d               # Last 7 days only

Shows per session: title (custom or auto), summary, all tags (color-coded by type), project name, age, model, cost, turn count, git branch, session ID, and resume command. First result's resume command is auto-copied to clipboard.

Session Listing

claude-tracker                           # All recent sessions
claude-tracker vscode                    # VS Code sessions only

When speculator is running, the session listing includes:

• Header: Ghostty tab count and window count alongside running/inactive/VS Code counts
• TTY badges: Purple s000–s010 badge per session showing which Ghostty tab it occupies

Detect Projects

node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js                # List all
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --suggest      # Suggest additions
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --scaffold     # Create CLAUDE.md stubs
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --since 30d    # Recent only

Update Active Projects

python3 ~/.claude/scripts/update-active-projects.py              # Regenerate active-projects.md
python3 ~/.claude/scripts/update-activ