{"id":"764baae9-2738-4ca5-800e-fa8fa56ae165","slug":"tracecc","kind":"skill","name":"TraceCC","summary":"TraceCC gives AI agents a CLI-native long-term memory over their own session history. Searchable, scoped, and sized for context windows.","owner":"lludlow","repoUrl":"https://github.com/lludlow/TraceCC","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-12T01:04:00.000Z","addedAt":"2026-10-22T00:53:11.584Z","logoUrl":"https://avatars.githubusercontent.com/u/2191492?u=9d2a1b723f828597516d3d585685c3b192860717&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","search"],"tags":["agent-memory","ai-agents","claude-code","llm-tools","long-term-memory","agent-traces","ai-memory","cli"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T23:12:03.135Z","sample":false,"url":"https://conduits.dev/tools/tracecc","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# TraceCC\n\n[![Release](https://img.shields.io/github/v/release/lludlow/TraceCC?style=flat-square)](https://github.com/lludlow/TraceCC/releases)\n[![Go](https://img.shields.io/github/go-mod/go-version/lludlow/TraceCC?style=flat-square)](https://go.dev)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n\nTraceCC gives AI agents a CLI-native long-term memory over their own session history. Searchable, scoped, and sized for context windows.\n\nCurrently supports **Claude Code**, **Codex**, and **Hermes Agent** JSONL traces. The adapter architecture is designed for additional runtimes without renderer changes.\n\nCurrent 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.\n\n- **Zero summarization loss.** The actual transcript, not someone's summary of it.\n- **Token-efficient.** Search returns pointers and snippets, not full sessions.\n- **Agent-native.** CLI tool, JSON output, designed for tool_call workflows.\n- **Multi-agent.** Claude Code, Codex, and Hermes traces unified in one index.\n- **Project-scoped.** One bundle per project, not one global blob.\n\nThe view model is informed by [\"View-oriented Conversation Compiler for Agent Trace Analysis\"](https://arxiv.org/abs/2603.29678).\n\n## Installation\n\nDownload a prebuilt binary from [GitHub Releases](https://github.com/lludlow/TraceCC/releases) and place it on your PATH:\n\n```bash\n# Example: macOS ARM64\ntar xzf tracecc_*_darwin_arm64.tar.gz\ncp tracecc_*_darwin_arm64/tracecc ~/.local/bin/\n```\n\nAvailable platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.\n\n### Build from source\n\nCGO is required (SQLite C binding).\n\n```bash\nCGO_ENABLED=1 go build -tags sqlite_fts5 ./cmd/tracecc\ncp tracecc ~/.local/bin/\n```\n\n### Claude Code skill\n\nTraceCC ships skills for each supported harness. Copy the one matching your agent:\n\n```bash\n# Claude Code\ncp -r skills/claude-code/tracecc ~/.claude/skills/\n\n# Codex\ncp -r skills/codex/tracecc ~/.agents/skills/\n\n# Hermes Agent\ncp -r skills/hermes/tracecc ~/.hermes/skills/\n```\n\nSee the skill definitions for each harness under [skills/](skills/).\n\n### Run tests\n\n```bash\nCGO_ENABLED=1 go test -tags sqlite_fts5 ./...\n```\n\n## Help\n\n<!-- help-start -->\n\n```bash\ntracecc --help\n```\n\n```\ntracecc compiles raw agent traces into an indexed .tcc bundle, then renders\nmultiple views and runs structured search over that bundle.\n\nThe important model is:\n  - compile once\n  - preserve a canonical full-view line map\n  - derive UI and adaptive views from that same coordinate system\n  - return pointers that let an agent jump back into full context\n\nUsage:\n  tracecc [flags]\n\n\nExamples:\n  # Compile all traces from config (run \"tracecc setup\" first)\n  tracecc compile --bundle traces.tcc --redact default\n\n  # Render the human-facing view for the latest session\n  tracecc render traces.tcc --view ui --session latest\n\n  # Search across a bundle or directory of bundles\n  tracecc search traces.tcc --query captcha --mode bm25 --roles tool_error,assistant\n\n  # Export text artifacts for downstream tools\n  tracecc export traces.tcc --out exports/\n\n  # Inspect sessions, nodes, or a full-view line range\n  tracecc inspect traces.tcc --sessions\n  tracecc inspect traces.tcc --node 42\n  tracecc inspect traces.tcc --lines 120:160\n\n  # Discover trace locations and save central config under ~/.TraceCC\n  tracecc setup\n\n  # Check the local environment and SQLite support\n  tracecc doctor\n\nCommands:\n  adapters    List available adapters\n  compile     Compile raw traces into a .tcc bundle\n  doctor      Check environment, config health, and adapter hints\n  export      Export text artifacts derived from a bundle\n  inspect     Inspect bundle internals for debugging and dereferencing\n  render      Render full, UI, or adaptive views from a bundle\n  search      Search one bundle or a directory of bundles\n  setup       Discover local trace roots and write central config\n  version     Print TraceCC build information\n\n\nOptions:\n  -h, --help    help for tracecc\n      --json    Print setup output as JSON. Only applies with --setup.\n      --setup   Shortcut for \"tracecc setup\". Only affects setup; ignored by other commands.\n      --yes     Accept discovered setup without prompting. Only applies with --setup.\n\nNotes:\ntracecc is designed for agent workflows. Search and render output always aim\nto preserve semantic role, source provenance, and a dereference path back into\nthe full transcript. Use \"tracecc <command> --help\" for command-specific\nbehavior and examples.\n```\n\n### tracecc compile\n\n```bash\ntracecc compile --help\n```\n\n```\nCompile discovers input traces, parses them through an adapter, normalizes\ntheir events, assigns immutable full-view line numbers, and writes a single\nSQLite-backed .tcc bundle.\n\nWhen called with no inputs, compile reads ~/.TraceCC/config.toml and walks all\nconfigured trace_roots recursively. Run \"tracecc setup\" first to generate this\nconfig. Explicit inputs override config discovery.\n\nAgents should use this first when they want stable line pointers, rendering, or\nsearch over large traces without reparsing raw JSONL each time.\n\nUsage:\n  tracecc compile [inputs...] [flags]\n\n\nExamples:\n  # Compile all traces discovered from ~/.TraceCC/config.toml\n  tracecc compile --bundle project.tcc --redact default\n\n  # Compile a single trace file explicitly\n  tracecc compile trace.jsonl --bundle session.tcc\n\n  # Compile a directory recursively and stamp the project name\n  tracecc compile traces/ --recursive --bundle project.tcc --project checkout\n\n  # Compile with adapter auto-detection and default secret redaction\n  tracecc compile traces/**/*.jsonl --adapter auto --bundle out.tcc --redact default --json\n\n  # Compile everything, ignoring project scope\n  tracecc compile --bundle all.tcc --redact default --all\n\nOptions:\n      --adapter string         Adapter to use. \"auto\" probes the input and selects a parser. (default \"auto\")\n      --all                    Ingest all sessions from all trace roots, bypassing project scoping.\n      --artifact-mode string   Artifact storage mode: off, sidecar, or embedded. The MVP stores refs only. (default \"off\")\n      --bundle string          Output bundle path. Defaults to tracecc.tcc in the current directory.\n      --extract-artifacts      Extract artifact payloads when artifact handling is enabled.\n      --fail-fast              Stop on the first input or parse error instead of collecting warnings.\n  -h, --help                   help for compile\n      --json                   Print the compile result as JSON instead of plain text.\n      --project string         Project label to stamp onto compiled sessions for later filtering.\n      --recursive              Walk input directories recursively when discovering trace files.\n      --redact string          Apply a named redaction policy before persistence. \"default\" strips API keys, tokens, secrets, and credentials. Currently the only available policy.\n      --threads int            Worker count hint (not yet implemented). Current compilation is single-process. (default 1)\n\nNotes:\nWhen no inputs are given, compile uses trace roots from ~/.TraceCC/config.toml.\nIf the config does not exist, compile exits with an error directing you to run\n\"tracecc setup\". By default, compile only ingests sessions belonging to declared\nprojects. Use --all to ingest everything from all trace roots regardless of\nproject scope. Compile output is the foundation for all later commands. Once\ncompiled, render and search operate on the bundle rather than the original JSONL.\nUse --redact default when traces may contain secrets.\n```\n\n### tracecc render\n\n```bash\ntracecc render --help\n```\n\n```\nRender reads compiled nodes from a bundle and projects them into one of three\nviews:\n  - full: lossless transcript with canonical line numbers\n  - ui: human-facing summary that collapses internal detail\n  - adaptive: query-driven projection that keeps full-view pointers\n\nAgents should prefer UI view for quick situational awareness and adaptive view\nfor focused retrieval. Use full view when exact transcript fidelity matters.\n\nUsage:\n  tracecc render <bundle.tcc> [flags]\n\n\nExamples:\n  # Show the full transcript for the latest session\n  tracecc render traces.tcc --view full --session latest\n\n  # Show the human-facing UI view\n  tracecc render traces.tcc --view ui\n\n  # Show only query-relevant blocks while keeping pointers to full view\n  tracecc render traces.tcc --view adaptive --mode document --query captcha\n\n  # Emit JSON instead of plain text\n  tracecc render traces.tcc --view full --format json\n\nOptions:\n      --format string        Output format. Use json for machine-readable full-view output. (default \"text\")\n  -h, --help                 help for render\n      --mode string          Adaptive mode: document keeps structure; index emits flat matches. (default \"document\")\n      --query string         Query used by adaptive rendering. Interpreted by --search-mode.\n      --roles strings        Restrict rendering to specific roles. Valid: user, assistant, tool_call, tool_result, tool_error, system, thinking, meta.\n      --search-mode string   Predicate type for adaptive rendering. Current default is regex. (default \"regex\")\n      --session string       Session to render: a session id, \"latest\", or \"all\". Empty resolves to the latest session. Use \"all\" for cross-session adaptive rendering.\n      --truncate int         Maximum visible lines per non-user block in UI view. 0 disables truncation.\n      --truncate-user int    Maximum visible lines for user blocks in UI view. 0 disables truncation.\n      --view string          View to render: full, ui, or adaptive. (default \"full\")\n\nNotes:\nLine numbers in all rendered output refer to the canonical full view. UI and\nadaptive renderers should be treated as projections over the same coordinate\nsystem, not separate transcripts.\n```\n\n### tracecc search\n\n```bash\ntracecc search --help\n```\n\n```\nSearch runs over compiled node content and returns structured results that\npreserve:\n  - semantic role\n  - source path\n  - session id\n  - line-range pointers back into full view\n\nUse regex when you know the exact pattern. Use bm25 when you want ranked text\nretrieval over larger bundle sets.\n\nUsage:\n  tracecc search <bundle-or-dir> [flags]\n\n\nExamples:\n  # Regex search within a single bundle\n  tracecc search traces.tcc --query \"captcha|challenge\" --mode regex\n\n  # BM25 search across a directory of bundles\n  tracecc search bundles/ --query \"checkpoint corruption\" --mode bm25 --limit 10\n\n  # Restrict search to assistant and tool_error blocks\n  tracecc search traces.tcc --query timeout --roles assistant,tool_error\n\n  # Emit machine-readable results\n  tracecc search traces.tcc --query captcha --mode bm25 --format json\n\nOptions:\n      --format string     Output format: text, json, or ndjson. (default \"text\")\n  -h, --help              help for search\n      --limit int         Maximum number of results to return after ranking and filtering. (default 20)\n      --mode string       Search mode: regex for exact patterns, bm25 for natural-language ranked retrieval. (default \"regex\")\n      --model strings     Restrict matches to one or more model names.\n      --offset int        Result offset for pagination.\n      --project strings   Restrict matches to one or more project labels.\n      --query string      Query text. Required for both regex and bm25 search.\n      --roles strings     Restrict matches to specific roles. Valid: user, assistant, tool_call, tool_result, tool_error, system, thinking, meta.\n      --runtime strings   Restrict matches to one or more source runtimes.\n      --since string      Only include sessions on or after this date. Accepts RFC3339 or YYYY-MM-DD.\n      --until string      Only include sessions on or before this date. Accepts RFC3339 or YYYY-MM-DD.\n\nNotes:\nUse bm25 for natural-language queries (\"what errors happened\") and regex for\nexact patterns (function names, error codes). Text output is optimized for quick\nscanning. JSON output is better for agents that want to chain search results into\nlater render or inspect calls. Use \"tracecc inspect --sessions\" to discover valid\nproject, model, and runtime values in a bundle.\n```\n\n### tracecc export\n\n```bash\ntracecc export --help\n```\n\n```\nExport writes text files derived from compiled bundle contents:\n  - .txt for full view\n  - .min.txt for concise UI-oriented view\n  - .view.txt for query-oriented adaptive output\n\nUse this when another tool or agent wants durable text files instead of live\nCLI output.\n\nUsage:\n  tracecc export <bundle.tcc> [flags]\n\n\nExamples:\n  # Export all text views to a directory\n  tracecc export traces.tcc --out exports/\n\n  # Export a specific session only\n  tracecc export traces.tcc --session sess-alpha --out exports/\n\n  # Export separate files per session\n  tracecc export traces.tcc --split-sessions --out exports/\n\nOptions:\n      --compat           Write all three text exports (.txt, .min.txt, .view.txt). Set false to write only the views selected by --view. (default true)\n  -h, --help             help for export\n      --out string       Output directory. Defaults to the current working directory.\n      --overwrite        Replace existing output files instead of failing.\n      --query string     Query text used to build .view.txt adaptive output.\n      --session string   Session id to export. Empty uses the latest session unless --split-sessions is set.\n      --split-sessions   Export each session separately instead of choosing one session.\n      --view string      Reserved for future view-specific export selection.\n\nNotes:\nExport files are derived from bundle contents and keep the same pointer semantics\nas live render output. They are intended for interoperability and downstream\ntooling, not as an alternate source of truth.\n```\n\n### tracecc inspect\n\n```bash\ntracecc inspect --help\n```\n\n```\nInspect exposes bundle metadata that is useful when an agent needs to reason\nabout internals rather than just rendered text.\n\nChoose exactly one of:\n  - --sessions to list compiled sessions\n  - --node <id> to inspect one IR node and its edges\n  - --lines <start:end> to retrieve full-view line text\n\nUsage:\n  tracecc inspect <bundle.tcc> [flags]\n\n\nExamples:\n  # List sessions and their metadata\n  tracecc inspect traces.tcc --sessions\n\n  # Inspect one node and its linked edges\n  tracecc inspect traces.tcc --node 1882\n\n  # Retrieve a full-view line range\n  tracecc inspect traces.tcc --session sess-alpha --lines 240:310\n\nOptions:\n  -h, --help             help for inspect\n      --json             Emit inspect output as JSON. Sessions default to readable text when this is omitted.\n      --lines string     Full-view line range to retrieve, written as start:end.\n      --node int         Load one node by id, including linked edges.\n      --session string   Session id to use for line lookups. Empty resolves to the latest session.\n      --sessions         List all sessions stored in the bundle.\n\nNotes:\nInspect is the lowest-level user-facing command. Prefer render or search for\nnormal analysis, then use inspect when you need to verify pointers, edges, or\nbundle contents directly. Search results include line-range pointers (e.g.\n\"session:L71-L72\") -- use --lines to dereference them. Node IDs are internal\nIR identifiers shown in --node output, not line numbers.\n```\n\n### tracecc setup\n\n```bash\ntracecc setup --help\n```\n\n```\nSetup performs guided local onboarding for TraceCC.\n\nIt inspects the current project root, looks for known agent trace locations,\nand writes a central config file under ~/.TraceCC so later auto-detection can\nprefer configured adapters over guesswork.\n\nFor non-project-scoped agents, use --<agent> to register just the trace root\nwithout associating a project. Currently supported: --hermes.\n\nUsage:\n  tracecc setup [flags]\n\n\nExamples:\n  # Discover from the current directory and confirm interactively\n  tracecc setup\n\n  # Register the Hermes agent trace root only\n  tracecc setup --hermes --yes\n\n  # Write a config without prompting\n  tracecc setup --project /path/to/project --yes\n\n  # Preview or script setup output\n  tracecc setup --json\n\nOptions:\n      --config string    Config path override. Defaults to ~/.TraceCC/config.toml or TRACECC_CONFIG.\n  -h, --help             help for setup\n      --hermes           Register the hermes agent trace root without a project association.\n      --json             Print setup output as JSON.\n      --project string   Project root to associate with this setup run. Defaults to the current working directory.\n      --yes              Accept the discovered config without prompting.\n```\n\n### tracecc doctor\n\n```bash\ntracecc doctor --help\n```\n\n```\nDoctor validates the local environment that TraceCC depends on:\n  - current Go runtime\n  - SQLite availability\n  - write access to an output directory\n  - TraceCC build metadata\n  - central config presence and parseability\n  - configured trace-root adapter hints\n\nUsage:\n  tracecc doctor [flags]\n\n\nExamples:\n  # Check the current environment\n  tracecc doctor\n\n  # Verify that a specific output directory is writable\n  tracecc doctor --output ./exports\n\nOptions:\n  -h, --help            help for doctor\n      --output string   Directory to probe for write access. (default \".\")\n```\n\n<!-- help-end -->\n\n## Examples\n\n### Onboarding a new project\n\n```bash\n# Discover trace locations and write config\ntracecc setup\n\n# Compile all traces with secret redaction\ntracecc compile --bundle traces.tcc --redact default\n\n# Check what sessions were compiled\ntracecc inspect traces.tcc --sessions\n```\n\n### Searching past sessions\n\n```bash\n# Natural-language search across all sessions\ntracecc search traces.tcc --query \"database migration\" --mode bm25 --limit 10\n\n# Exact pattern match restricted to errors\ntracecc search traces.tcc --query \"timeout|deadline\" --mode regex --roles tool_error\n\n# Filter by date range\ntracecc search traces.tcc --query \"deploy\" --mode bm25 --since 2026-04-01 --until 2026-04-12\n```\n\n### Rendering views\n\n```bash\n# Human-readable summary of the latest session\ntracecc render traces.tcc --view ui --session latest\n\n# Full lossless transcript\ntracecc render traces.tcc --view full --session latest\n\n# Query-driven projection showing only relevant blocks\ntracecc render traces.tcc --view adaptive --query \"error handling\" --session latest\n```\n\n### Dereferencing search results\n\nSearch results include line-range pointers like `session:L71-L72`. Dereference them with inspect:\n\n```bash\ntracecc inspect traces.tcc --lines 71:72\n```\n\n## Docs\n\n- [Architecture](./docs/architecture.md)\n- [Bundle Schema](./docs/schema.md)\n- [Renderer Guide](./docs/renderer-guide.md)\n- [Adapter Guide](./docs/adapter-guide.md)\n\n## AI Disclosure\n\nThis project was built using AI-augmented engineering. See\n[AI-DISCLOSURE.md](AI-DISCLOSURE.md) for details.\n\n## Citation\n\nTraceCC's view model is informed by:\n\nLvmin Zhang and Maneesh Agrawala. \"View-oriented Conversation Compiler for Agent Trace Analysis.\" arXiv:2603.29678, 2026. [https://doi.org/10.48550/arXiv.2603.29678](https://doi.org/10.48550/arXiv.2603.29678)\n\n```bibtex\n@article{zhang2026vcc,\n  title   = {View-oriented Conversation Compiler for Agent Trace Analysis},\n  author  = {Zhang, Lvmin and Agrawala, Maneesh},\n  journal = {arXiv preprint arXiv:2603.29678},\n  year    = {2026},\n  doi     = {10.48550/arXiv.2603.29678},\n  url     = {https://arxiv.org/abs/2603.29678}\n}\n```\n"}