---
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.

```bash
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:
```bash
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:
```bash
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:
```bash
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:**
```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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