tracecc

name	tracecc
description	Search and analyze past 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".
argument-hint	<search query or command>
allowed-tools	Bash(tracecc:*), Bash(rm:*), Bash(ls:*), Bash(wc:*), Read, Grep, Glob

TraceCC - Agent Trace Search & Analysis

Search, render, and analyze compiled agent session traces via the tracecc CLI.

Commands

Compile (rebuild the bundle)

Only recompile when the bundle is stale or missing. Compilation walks all configured trace roots from ~/.TraceCC/config.toml and produces a single SQLite-backed .tcc file.

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

Always use --redact default to scrub potential secrets. The default policy strips API keys, tokens, secrets, and credentials. It is currently the only available policy.

To compile everything regardless of project scope:

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

Search

The primary tool. Two modes:

BM25 (ranked relevance) - preferred for natural-language queries ("what errors happened", "scheduling discussion"). Returns results ranked by relevance:

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

Regex (exact patterns) - use for function names, error messages, specific strings. Returns results in document order:

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

Default mode is regex. When in doubt, use bm25 — it handles vague queries better.

Filters narrow results:

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

Common patterns:

# What errors happened recently?
tracecc search traces.tcc --query "error" --mode bm25 --roles tool_error --since 2026-04-01

# What did the user ask about a topic?
tracecc search traces.tcc --query "docker kubernetes" --mode bm25 --roles user --limit 10

# Find a specific function or variable
tracecc search traces.tcc --query "PersistentClaude" --mode regex --roles assistant,tool_call

Render

View a session's content in different projections. All views share canonical line numbers.

# 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 (shows only relevant blocks)
tracecc render traces.tcc --view adaptive --query "topic" --session <session-id>

The --session flag accepts a session ID, latest, or all:

• latest (default): renders the most recent session
• <session-id>: renders a specific session (get IDs from inspect --sessions or search results)
• all: renders across all sessions — use with --view adaptive when the topic may span multiple sessions

Inspect

Examine bundle internals and dereference pointers from search results. Also useful for discovering valid filter values.

# List all sessions (shows session IDs, projects, models, runtimes)
tracecc inspect traces.tcc --sessions

# Look at a specific node (node IDs are internal IR identifiers, not line numbers)
tracecc inspect traces.tcc --node 42

# Dereference a line range from a search result pointer (e.g. "session:L120-L160")
tracecc inspect traces.tcc --lines 120:160

Search result → inspect workflow: Search results include pointers like session:L71-L72. Extract the line numbers and pass them to --lines to retrieve the full text at that location.

Export

Write text files for downstream tools or archival.

# Export latest session
tracecc export traces.tcc --out exports/ --overwrite

# Export all sessions as separate files
tracecc export traces.tcc --split-sessions --out exports/ --overwrite

Workflow

"What did I say about X?" / "Find the session where..."

1. Start with BM25 search, broad query, limit 10
2. If results are noisy, add --roles or --since filters
3. Use session IDs from results to render --view ui for context
4. If the user needs exact text, use 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 in the output
3. Render UI view for sessions with interesting errors

"Show me recent sessions"

1. inspect --sessions and pipe through tail -20 for the most recent
2. For a specific date range: search --since YYYY-MM-DD --until YYYY-MM-DD --roles user --query "." --mode regex --limit 20

Bundle is missing or stale

If the dynamic context shows no bundle or the bundle is old:

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

Output

Present search results concisely. For each hit, show:

• Session ID (truncated to first 8 chars)
• Role in brackets
• Date if available
• The matching content (first 2-3 lines, not the full block)

When rendering a full session, use the UI view and summarize key exchanges rather than dumping the entire transcript.

Rules

• Always use --redact default when compiling
• Never expose raw bundle paths or internal IDs in user-facing output unless they ask
• If search returns nothing, try alternate query phrasings or broader filters before reporting "not found"
• The bundle is read-only after compile. Search and render never modify it.
• Recompile only when asked or when the bundle is clearly stale