tracecc

name	tracecc
description	Search and analyze past agent sessions using compiled trace bundles. Use when asked to recall previous conversations, find past sessions, search agent history, debug prior agent behavior, or answer "what did I say about X" / "when did we discuss Y" / "find the session where". Applies to "search traces", "past sessions", "trace search", "what happened last week", "show me recent errors".

TraceCC - Agent Trace Search & Analysis

Search, render, and analyze compiled agent session traces via the tracecc CLI. Compiles raw JSONL session traces into an indexed SQLite bundle with structured search and multiple view projections.

Commands

Compile

Rebuild only when the bundle is stale or missing. Walks all configured trace roots from ~/.TraceCC/config.toml.

tracecc compile --bundle traces.tcc --redact default --json

Always use --redact default to strip API keys, tokens, and credentials.

To compile everything regardless of project scope:

tracecc compile --bundle all.tcc --redact default --all

Search

BM25 (ranked relevance) for natural-language queries:

tracecc search traces.tcc --query "scheduling API cron" --mode bm25 --limit 10

Regex (exact patterns) for function names, error messages, specific strings:

tracecc search traces.tcc --query "summarize_diff" --mode regex --limit 10

Default mode is regex. Use bm25 for vague queries.

Filters:

• --roles user,assistant,tool_call,tool_result,tool_error - filter by message role
• --since 2026-04-01 / --until 2026-04-11 - date range (YYYY-MM-DD)
• --runtime codex - restrict to Codex sessions only
• --project, --model - filter by metadata (use inspect --sessions to discover values)
• --limit N - max results (default 20)
• --format json - machine-readable output

Render

# Human-readable summary of latest session
tracecc render traces.tcc --view ui --session latest

# Full lossless transcript
tracecc render traces.tcc --view full --session <session-id>

# Query-driven projection (only relevant blocks)
tracecc render traces.tcc --view adaptive --query "topic" --session all

Inspect

# List all sessions with metadata
tracecc inspect traces.tcc --sessions

# Dereference a line range from a search result (e.g. "session:L71-L72")
tracecc inspect traces.tcc --lines 71:72

Export

tracecc export traces.tcc --out exports/ --overwrite
tracecc export traces.tcc --split-sessions --out exports/ --overwrite

Workflows

"What did I say about X?"

1. BM25 search with broad query, limit 10
2. If noisy, add --roles or --since filters
3. Use session IDs from results to render --view ui
4. For exact text, inspect --lines with the line range from search

"What errors have we been hitting?"

1. search --roles tool_error --mode bm25 --query "error" --limit 20
2. Group by session ID
3. Render UI view for sessions with interesting errors

"Show me recent sessions"

1. inspect --sessions for the full list
2. For a date range: search --since YYYY-MM-DD --until YYYY-MM-DD --roles user --query "." --mode regex

Bundle missing or stale

1. Recompile: tracecc compile --bundle traces.tcc --redact default --json
2. Confirm session/event counts in output
3. Proceed with the query

Rules

• Always use --redact default when compiling
• Never expose raw bundle paths or internal IDs unless asked
• If search returns nothing, try alternate phrasings or broader filters before reporting "not found"
• The bundle is read-only after compile
• Recompile only when asked or when the bundle is clearly stale
• Line numbers in all output refer to canonical full-view coordinates