claude-tracker-suite

name	claude-tracker-suite
description	Manage Claude Code sessions — search by topic or ID, resume crashed sessions, spawn interactive or headless sessions, monitor live sessions, auto-summarize, and bootstrap new machine setups. Triggers on resume session, find session, list sessions, spawn session, session history, what was I working on.
argument-hint	["query or --id <prefix>"]
allowed-tools	Bash(claude-tracker*), Bash(node ~/.claude/skills/claude-tracker-suite/scripts/*), Bash(~/.claude/skills/claude-tracker-suite/scripts/*.sh), Bash(python3 ~/.claude/scripts/*), Read, Grep, Glob, Edit, Write, Skill

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

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

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.

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-active-projects.py --summarize  # Show sessions needing summaries

The generated table includes Model, Turns, and Cost columns from enriched session data (extracted from JSONL transcripts). Git worktree sessions show a tree emoji badge. Sessions without summaries are auto-named via one-shot claude --model haiku call.

Bootstrap New Setup

Generate a complete ~/.claude/ configuration for a new machine:

node ~/.claude/skills/claude-tracker-suite/scripts/bootstrap-claude-setup.js --user "Name" --dry-run
node ~/.claude/skills/claude-tracker-suite/scripts/bootstrap-claude-setup.js --user "Name"

Creates directory structure, global CLAUDE.md, userModel template, agent_docs stubs, and project CLAUDE.md scaffolds. Follow up with /claude-md-manager to enrich generated files.

Resume in New Terminal

Open a session in a new cmux tab, optionally opening the project in an editor:

# Resume in cmux tab (default — auto-detects project directory)
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id>

# Resume in cmux + open project in VS Code
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id> --vscode

# Resume in cmux + open project in Cursor
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id> --cursor

# Explicit project directory
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id> --project ~/Desktop/Programming

cmux owns the terminal lifecycle. Editor flags (--vscode, --cursor) only open the project in the editor — the session always resumes in cmux. Falls back to printing the resume command if cmux is not running.

New Session / Spawn

Start a new Claude Code session in a terminal tab or headless:

# Interactive session in Ghostty (default)
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project

# With a specific model
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --model opus

# Prompt-driven session in Ghostty tab
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --prompt "fix the login bug"

# Prompt-driven in VS Code terminal
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --vscode --prompt "fix the login bug"

# Headless — runs in current terminal, returns JSON
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --headless --prompt "summarize the README"

# Headless with specific model and output format
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --headless --prompt "fix tests" --model haiku --output-format text

Headless and prompt-driven modes use claude -p (the Agent SDK CLI). Note: -p is now officially part of the Claude Agent SDK—it uses SDK billing, not interactive session billing. Terminal modes use the clipboard-paste AppleScript pattern for reliable command delivery (handles special characters in prompts).

Workflow: Find and Resume

1. claude-tracker-search "topic" — find matching sessions
2. claude --resume <session-id> — resume in current terminal
3. open-sessions.js — list top sessions, open selected in cmux tabs
4. Or claude-tracker-resume --tmux — auto-resume all crashed sessions

Workflow: Open Sessions in cmux

List recent sessions and open them in cmux tabs or splits:

# List top 10, prompt for selection
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js

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

# Open all without confirmation
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --yes

# JSON output for scripting
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --json

Session directories are resolved from JSONL ground truth (decodeProjectPath), not from active-projects.md. Falls back to printing resume commands when cmux is unavailable.

For the full cmux CLI reference, see references/cmux-commands.md.

Workflow: Monitor Active Work

1. claude-tracker-alive — see what's running vs stale
2. claude-tracker-watch --daemon — keep summaries auto-updated
3. Read ~/.claude/agent_docs/active-projects.md — curated project overview

SQLite Database (tracker.db)

Single SQLite database at ~/.claude/tracker.db consolidates all session metadata, git tracking, tags, and three new capabilities: checkpoints, phase tracking, and tagged phrases.

API module: ~/.claude/lib/tracker-db.js — synchronous better-sqlite3, WAL mode, singleton lazy-open.

# Query directly
sqlite3 ~/.claude/tracker.db "SELECT COUNT(*) FROM sessions;"
sqlite3 ~/.claude/tracker.db "SELECT phase, COUNT(*) FROM phases GROUP BY phase;"
sqlite3 ~/.claude/tracker.db "SELECT phrase, GROUP_CONCAT(tag) FROM tagged_phrases tp LEFT JOIN tagged_phrase_tags tpt ON tpt.phrase_id = tp.id GROUP BY tp.id ORDER BY tp.timestamp DESC LIMIT 10;"

Migration (idempotent): node ~/.claude/scripts/migrate-to-sqlite.js

Checkpoints

Named bookmarks within sessions capturing label, git state, workflow phase, and modified files.

# Manual checkpoint
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js create "finished auth module"
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js create "pre-deploy" --summary "about to push"

# List checkpoints
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list --phase implementing
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list --limit 10

Auto-checkpoints are created on git commits (git-track-post.sh) and phase transitions (phase-detect.py).

Phase Tracking

Automatic workflow phase detection via PostToolUse hook (phase-detect.py). Rolling window of last 10 tool calls, hysteresis to prevent flickering.

Phases: exploring, planning, implementing, testing, reviewing, debugging, committing, deploying.

# Query current phase for a session
sqlite3 ~/.claude/tracker.db "SELECT phase, started_at FROM phases WHERE session_id = 'abc...' AND ended_at IS NULL;"

# Phase history
sqlite3 ~/.claude/tracker.db "SELECT phase, started_at, ended_at, duration_ms FROM phases WHERE session_id = 'abc...' ORDER BY started_at;"

# Phase analytics
sqlite3 ~/.claude/tracker.db "SELECT phase, COUNT(*) as transitions, AVG(duration_ms)/1000 as avg_seconds FROM phases GROUP BY phase;"

Tagged Phrases

Notable excerpts captured from sessions with tags, searchable via FTS5.

# Capture a phrase
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js capture "assumptions are the enemy" --tags principle,design

# Search phrases (FTS5)
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js search "assumptions"

# List by tag
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js tag principle

# List recent phrases
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js list --limit 20

Phrases are also auto-extracted by the session-tags-infer.py Stop hook during LLM inference.

Related: Git Tracking

Git-aware session tracking via PreToolUse/PostToolUse hooks intercepts all git commands and tags sessions with repos they touch. Enables cross-directory session discovery.

File	Purpose
~/.claude/hooks/git-track.sh	PreToolUse hook — logs git commands to JSONL
~/.claude/hooks/git-track-post.sh	PostToolUse hook — captures commit hashes
~/.claude/hooks/git-track-rebuild.py	Builds bidirectional index at SessionEnd
~/.claude/git-tracking.jsonl	Append-only event log (hot path)
~/.claude/git-tracking-index.json	Bidirectional session <-> repo index

Query functions in tracker-utils.js:

• loadGitTracking() — load the index
• getSessionsForRepo(path) — find sessions that touched a repo
• getReposForSession(sid) — find repos a session touched
• getRecentCommits({hours, repoPath}) — recent commits across sessions
• getRecentGitEvents({hours}) — raw event timeline
• loadSpeculatorData() — load speculator snapshot (Ghostty tab → session map)
• getSessionTTY(sessionId, speculatorData) — look up Ghostty TTY for a session

The /session-report command generates a Markdown dashboard combining session status with git activity.

Related: Speculator (Ghostty Tab Map)

The speculator daemon (~/.claude/scripts/speculator/) maps Ghostty terminal tabs to running Claude Code sessions every 5 minutes. It integrates with the tracker suite via two functions in tracker-utils.js:

Function	Purpose
loadSpeculatorData()	Load latest speculator snapshot (returns null if stale >10min or missing)
getSessionTTY(sessionId, speculatorData)	Look up which Ghostty TTY a session is running on

list-sessions.js uses these to add Ghostty tab counts to the header and purple TTY badges per session. The snapshot JSON at ~/.claude/scripts/speculator/data/ghostty-sessions.json is also available for direct consumption by other tools.

The Markdown view is synced to ~/.claude/agent_docs/ghostty-sessions.md for on-demand reading by any Claude session.

Check daemon health: bash ~/.claude/scripts/speculator/status.sh

Related: Soul Registry

The soul registry (~/.claude/hooks/soul-registry.py) tracks live sessions with heartbeats, topics, and Slack channel bindings. It complements the tracker suite:

	Tracker Suite	Soul Registry
Scope	All sessions, all time	Active sessions only
Data source	JSONL transcripts, sessions-index.json	~/.claude/soul-sessions/registry.json
Updates	After session ends (summaries)	Real-time (heartbeat every turn)
Purpose	Search, resume, project detection	Cross-session awareness, Slack binding

To view the live registry: python3 ~/.claude/hooks/soul-registry.py list --md

To activate Claudicle identity in a session: /ensoul (opt-in per session). To bind a session to Slack: /slack-sync #channel.

References

For detailed schemas and infrastructure:

• references/data-schemas.md — Session index, summary cache, and JSONL transcript schemas; data source locations; shared library API
• references/daemon-setup.md — Watcher daemon lifecycle and launchd plist template
• references/cmux-commands.md — Complete cmux CLI reference: hierarchy, splits, tabs, input, browser, sidebar, notifications, keyboard shortcuts