TraceCC gives AI agents a CLI-native long-term memory over their own session history. Searchable, scoped, and sized for context windows.
Currently supports Claude Code, Codex, and Hermes Agent JSONL traces. The adapter architecture is designed for additional runtimes without renderer changes.
Current agent memory is either summarized (lossy, someone decided what mattered at write time) or raw traces (lossless but useless without parsing hundreds of JSONL files). TraceCC sits in between. The agent runs a CLI call, gets back targeted results with stable pointers, and can drill deeper only if needed. The token cost is a search result, not a transcript.
- Zero summarization loss. The actual transcript, not someone's summary of it.
- Token-efficient. Search returns pointers and snippets, not full sessions.
- Agent-native. CLI tool, JSON output, designed for tool_call workflows.
- Multi-agent. Claude Code, Codex, and Hermes traces unified in one index.
- Project-scoped. One bundle per project, not one global blob.
The view model is informed by "View-oriented Conversation Compiler for Agent Trace Analysis".
Download a prebuilt binary from GitHub Releases and place it on your PATH:
# Example: macOS ARM64
tar xzf tracecc_*_darwin_arm64.tar.gz
cp tracecc_*_darwin_arm64/tracecc ~/.local/bin/Available platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.
CGO is required (SQLite C binding).
CGO_ENABLED=1 go build -tags sqlite_fts5 ./cmd/tracecc
cp tracecc ~/.local/bin/TraceCC ships skills for each supported harness. Copy the one matching your agent:
# Claude Code
cp -r skills/claude-code/tracecc ~/.claude/skills/
# Codex
cp -r skills/codex/tracecc ~/.agents/skills/
# Hermes Agent
cp -r skills/hermes/tracecc ~/.hermes/skills/See the skill definitions for each harness under skills/.
CGO_ENABLED=1 go test -tags sqlite_fts5 ./...tracecc --helptracecc compiles raw agent traces into an indexed .tcc bundle, then renders
multiple views and runs structured search over that bundle.
The important model is:
- compile once
- preserve a canonical full-view line map
- derive UI and adaptive views from that same coordinate system
- return pointers that let an agent jump back into full context
Usage:
tracecc [flags]
Examples:
# Compile all traces from config (run "tracecc setup" first)
tracecc compile --bundle traces.tcc --redact default
# Render the human-facing view for the latest session
tracecc render traces.tcc --view ui --session latest
# Search across a bundle or directory of bundles
tracecc search traces.tcc --query captcha --mode bm25 --roles tool_error,assistant
# Export text artifacts for downstream tools
tracecc export traces.tcc --out exports/
# Inspect sessions, nodes, or a full-view line range
tracecc inspect traces.tcc --sessions
tracecc inspect traces.tcc --node 42
tracecc inspect traces.tcc --lines 120:160
# Discover trace locations and save central config under ~/.TraceCC
tracecc setup
# Check the local environment and SQLite support
tracecc doctor
Commands:
adapters List available adapters
compile Compile raw traces into a .tcc bundle
doctor Check environment, config health, and adapter hints
export Export text artifacts derived from a bundle
inspect Inspect bundle internals for debugging and dereferencing
render Render full, UI, or adaptive views from a bundle
search Search one bundle or a directory of bundles
setup Discover local trace roots and write central config
version Print TraceCC build information
Options:
-h, --help help for tracecc
--json Print setup output as JSON. Only applies with --setup.
--setup Shortcut for "tracecc setup". Only affects setup; ignored by other commands.
--yes Accept discovered setup without prompting. Only applies with --setup.
Notes:
tracecc is designed for agent workflows. Search and render output always aim
to preserve semantic role, source provenance, and a dereference path back into
the full transcript. Use "tracecc <command> --help" for command-specific
behavior and examples.
tracecc compile --helpCompile discovers input traces, parses them through an adapter, normalizes
their events, assigns immutable full-view line numbers, and writes a single
SQLite-backed .tcc bundle.
When called with no inputs, compile reads ~/.TraceCC/config.toml and walks all
configured trace_roots recursively. Run "tracecc setup" first to generate this
config. Explicit inputs override config discovery.
Agents should use this first when they want stable line pointers, rendering, or
search over large traces without reparsing raw JSONL each time.
Usage:
tracecc compile [inputs...] [flags]
Examples:
# Compile all traces discovered from ~/.TraceCC/config.toml
tracecc compile --bundle project.tcc --redact default
# Compile a single trace file explicitly
tracecc compile trace.jsonl --bundle session.tcc
# Compile a directory recursively and stamp the project name
tracecc compile traces/ --recursive --bundle project.tcc --project checkout
# Compile with adapter auto-detection and default secret redaction
tracecc compile traces/**/*.jsonl --adapter auto --bundle out.tcc --redact default --json
# Compile everything, ignoring project scope
tracecc compile --bundle all.tcc --redact default --all
Options:
--adapter string Adapter to use. "auto" probes the input and selects a parser. (default "auto")
--all Ingest all sessions from all trace roots, bypassing project scoping.
--artifact-mode string Artifact storage mode: off, sidecar, or embedded. The MVP stores refs only. (default "off")
--bundle string Output bundle path. Defaults to tracecc.tcc in the current directory.
--extract-artifacts Extract artifact payloads when artifact handling is enabled.
--fail-fast Stop on the first input or parse error instead of collecting warnings.
-h, --help help for compile
--json Print the compile result as JSON instead of plain text.
--project string Project label to stamp onto compiled sessions for later filtering.
--recursive Walk input directories recursively when discovering trace files.
--redact string Apply a named redaction policy before persistence. "default" strips API keys, tokens, secrets, and credentials. Currently the only available policy.
--threads int Worker count hint (not yet implemented). Current compilation is single-process. (default 1)
Notes:
When no inputs are given, compile uses trace roots from ~/.TraceCC/config.toml.
If the config does not exist, compile exits with an error directing you to run
"tracecc setup". By default, compile only ingests sessions belonging to declared
projects. Use --all to ingest everything from all trace roots regardless of
project scope. Compile output is the foundation for all later commands. Once
compiled, render and search operate on the bundle rather than the original JSONL.
Use --redact default when traces may contain secrets.
tracecc render --helpRender reads compiled nodes from a bundle and projects them into one of three
views:
- full: lossless transcript with canonical line numbers
- ui: human-facing summary that collapses internal detail
- adaptive: query-driven projection that keeps full-view pointers
Agents should prefer UI view for quick situational awareness and adaptive view
for focused retrieval. Use full view when exact transcript fidelity matters.
Usage:
tracecc render <bundle.tcc> [flags]
Examples:
# Show the full transcript for the latest session
tracecc render traces.tcc --view full --session latest
# Show the human-facing UI view
tracecc render traces.tcc --view ui
# Show only query-relevant blocks while keeping pointers to full view
tracecc render traces.tcc --view adaptive --mode document --query captcha
# Emit JSON instead of plain text
tracecc render traces.tcc --view full --format json
Options:
--format string Output format. Use json for machine-readable full-view output. (default "text")
-h, --help help for render
--mode string Adaptive mode: document keeps structure; index emits flat matches. (default "document")
--query string Query used by adaptive rendering. Interpreted by --search-mode.
--roles strings Restrict rendering to specific roles. Valid: user, assistant, tool_call, tool_result, tool_error, system, thinking, meta.
--search-mode string Predicate type for adaptive rendering. Current default is regex. (default "regex")
--session string Session to render: a session id, "latest", or "all". Empty resolves to the latest session. Use "all" for cross-session adaptive rendering.
--truncate int Maximum visible lines per non-user block in UI view. 0 disables truncation.
--truncate-user int Maximum visible lines for user blocks in UI view. 0 disables truncation.
--view string View to render: full, ui, or adaptive. (default "full")
Notes:
Line numbers in all rendered output refer to the canonical full view. UI and
adaptive renderers should be treated as projections over the same coordinate
system, not separate transcripts.
tracecc search --helpSearch runs over compiled node content and returns structured results that
preserve:
- semantic role
- source path
- session id
- line-range pointers back into full view
Use regex when you know the exact pattern. Use bm25 when you want ranked text
retrieval over larger bundle sets.
Usage:
tracecc search <bundle-or-dir> [flags]
Examples:
# Regex search within a single bundle
tracecc search traces.tcc --query "captcha|challenge" --mode regex
# BM25 search across a directory of bundles
tracecc search bundles/ --query "checkpoint corruption" --mode bm25 --limit 10
# Restrict search to assistant and tool_error blocks
tracecc search traces.tcc --query timeout --roles assistant,tool_error
# Emit machine-readable results
tracecc search traces.tcc --query captcha --mode bm25 --format json
Options:
--format string Output format: text, json, or ndjson. (default "text")
-h, --help help for search
--limit int Maximum number of results to return after ranking and filtering. (default 20)
--mode string Search mode: regex for exact patterns, bm25 for natural-language ranked retrieval. (default "regex")
--model strings Restrict matches to one or more model names.
--offset int Result offset for pagination.
--project strings Restrict matches to one or more project labels.
--query string Query text. Required for both regex and bm25 search.
--roles strings Restrict matches to specific roles. Valid: user, assistant, tool_call, tool_result, tool_error, system, thinking, meta.
--runtime strings Restrict matches to one or more source runtimes.
--since string Only include sessions on or after this date. Accepts RFC3339 or YYYY-MM-DD.
--until string Only include sessions on or before this date. Accepts RFC3339 or YYYY-MM-DD.
Notes:
Use bm25 for natural-language queries ("what errors happened") and regex for
exact patterns (function names, error codes). Text output is optimized for quick
scanning. JSON output is better for agents that want to chain search results into
later render or inspect calls. Use "tracecc inspect --sessions" to discover valid
project, model, and runtime values in a bundle.
tracecc export --helpExport writes text files derived from compiled bundle contents:
- .txt for full view
- .min.txt for concise UI-oriented view
- .view.txt for query-oriented adaptive output
Use this when another tool or agent wants durable text files instead of live
CLI output.
Usage:
tracecc export <bundle.tcc> [flags]
Examples:
# Export all text views to a directory
tracecc export traces.tcc --out exports/
# Export a specific session only
tracecc export traces.tcc --session sess-alpha --out exports/
# Export separate files per session
tracecc export traces.tcc --split-sessions --out exports/
Options:
--compat Write all three text exports (.txt, .min.txt, .view.txt). Set false to write only the views selected by --view. (default true)
-h, --help help for export
--out string Output directory. Defaults to the current working directory.
--overwrite Replace existing output files instead of failing.
--query string Query text used to build .view.txt adaptive output.
--session string Session id to export. Empty uses the latest session unless --split-sessions is set.
--split-sessions Export each session separately instead of choosing one session.
--view string Reserved for future view-specific export selection.
Notes:
Export files are derived from bundle contents and keep the same pointer semantics
as live render output. They are intended for interoperability and downstream
tooling, not as an alternate source of truth.
tracecc inspect --helpInspect exposes bundle metadata that is useful when an agent needs to reason
about internals rather than just rendered text.
Choose exactly one of:
- --sessions to list compiled sessions
- --node <id> to inspect one IR node and its edges
- --lines <start:end> to retrieve full-view line text
Usage:
tracecc inspect <bundle.tcc> [flags]
Examples:
# List sessions and their metadata
tracecc inspect traces.tcc --sessions
# Inspect one node and its linked edges
tracecc inspect traces.tcc --node 1882
# Retrieve a full-view line range
tracecc inspect traces.tcc --session sess-alpha --lines 240:310
Options:
-h, --help help for inspect
--json Emit inspect output as JSON. Sessions default to readable text when this is omitted.
--lines string Full-view line range to retrieve, written as start:end.
--node int Load one node by id, including linked edges.
--session string Session id to use for line lookups. Empty resolves to the latest session.
--sessions List all sessions stored in the bundle.
Notes:
Inspect is the lowest-level user-facing command. Prefer render or search for
normal analysis, then use inspect when you need to verify pointers, edges, or
bundle contents directly. Search results include line-range pointers (e.g.
"session:L71-L72") -- use --lines to dereference them. Node IDs are internal
IR identifiers shown in --node output, not line numbers.
tracecc setup --helpSetup performs guided local onboarding for TraceCC.
It inspects the current project root, looks for known agent trace locations,
and writes a central config file under ~/.TraceCC so later auto-detection can
prefer configured adapters over guesswork.
For non-project-scoped agents, use --<agent> to register just the trace root
without associating a project. Currently supported: --hermes.
Usage:
tracecc setup [flags]
Examples:
# Discover from the current directory and confirm interactively
tracecc setup
# Register the Hermes agent trace root only
tracecc setup --hermes --yes
# Write a config without prompting
tracecc setup --project /path/to/project --yes
# Preview or script setup output
tracecc setup --json
Options:
--config string Config path override. Defaults to ~/.TraceCC/config.toml or TRACECC_CONFIG.
-h, --help help for setup
--hermes Register the hermes agent trace root without a project association.
--json Print setup output as JSON.
--project string Project root to associate with this setup run. Defaults to the current working directory.
--yes Accept the discovered config without prompting.
tracecc doctor --helpDoctor validates the local environment that TraceCC depends on:
- current Go runtime
- SQLite availability
- write access to an output directory
- TraceCC build metadata
- central config presence and parseability
- configured trace-root adapter hints
Usage:
tracecc doctor [flags]
Examples:
# Check the current environment
tracecc doctor
# Verify that a specific output directory is writable
tracecc doctor --output ./exports
Options:
-h, --help help for doctor
--output string Directory to probe for write access. (default ".")
# Discover trace locations and write config
tracecc setup
# Compile all traces with secret redaction
tracecc compile --bundle traces.tcc --redact default
# Check what sessions were compiled
tracecc inspect traces.tcc --sessions# Natural-language search across all sessions
tracecc search traces.tcc --query "database migration" --mode bm25 --limit 10
# Exact pattern match restricted to errors
tracecc search traces.tcc --query "timeout|deadline" --mode regex --roles tool_error
# Filter by date range
tracecc search traces.tcc --query "deploy" --mode bm25 --since 2026-04-01 --until 2026-04-12# Human-readable summary of the latest session
tracecc render traces.tcc --view ui --session latest
# Full lossless transcript
tracecc render traces.tcc --view full --session latest
# Query-driven projection showing only relevant blocks
tracecc render traces.tcc --view adaptive --query "error handling" --session latestSearch results include line-range pointers like session:L71-L72. Dereference them with inspect:
tracecc inspect traces.tcc --lines 71:72This project was built using AI-augmented engineering. See AI-DISCLOSURE.md for details.
TraceCC's view model is informed by:
Lvmin Zhang and Maneesh Agrawala. "View-oriented Conversation Compiler for Agent Trace Analysis." arXiv:2603.29678, 2026. https://doi.org/10.48550/arXiv.2603.29678
@article{zhang2026vcc,
title = {View-oriented Conversation Compiler for Agent Trace Analysis},
author = {Zhang, Lvmin and Agrawala, Maneesh},
journal = {arXiv preprint arXiv:2603.29678},
year = {2026},
doi = {10.48550/arXiv.2603.29678},
url = {https://arxiv.org/abs/2603.29678}
}