Semantic code intelligence for AI coding agents

Fewer tokens • fewer tool calls • local by default

TraceDecay builds a local semantic graph of your repository so AI coding agents can ask for the right symbols, call relationships, impact radius, docs, and source snippets without scanning the tree.

Instead of repeated grep, glob, and file reads, agents use MCP tools such as tracedecay_context, tracedecay_search, tracedecay_callers, and tracedecay_impact.

Highlights

• Typed MCP operations for discovery, call graphs, impact analysis, code health, test mapping, repository context, and anchored edits.
• Rust tree-sitter extractors with lite/medium/full Cargo feature tiers; Cargo.toml is the exact language authority.
• Native integrations for supported Claude Code, Codex, Cursor, Hermes, Kiro, Kimi Code, OpenCode, and Cline-family hosts.
• Daemon-owned local storage through the rusqlite runtime and embedded Grafeo graph store. Local operation is the default; configured remote sources and authorities follow explicit policy rather than an implicit local-only guarantee.
• On-demand freshness checks with exact repository, worktree, ref, commit, and generation provenance across linked git worktrees.
• Project-wide facts, sessions, and lossless LCM history remain available across branches; historical host transcripts enter through the same sanitized daemon ingestion path.
• Local dashboard for evidence, memory, LCM sessions, savings, and cost analytics.

Install

# Linux and Apple silicon macOS
curl -fsSL https://github.com/ScriptedAlchemy/tracedecay/releases/latest/download/install.sh | bash

# Windows: download the x86_64 Windows archive from the latest release,
# extract tracedecay.exe, and place it on PATH.

The installer defaults to ~/.local/bin. Set TRACEDECAY_INSTALL_DIR to choose another directory. Prebuilt archives are available on the latest release.

Final V2 storage model

tracedecay-graph-db is the sole Grafeo dependency boundary. Final V2 accepts only its exact persisted shape: an incompatible store returns ResetRequired and requires explicit reset or recreation, never conversion. See the V2 operating model.

Quick Start

cd /path/to/your/project
tracedecay init
tracedecay install
tracedecay status

tracedecay install auto-detects supported agents. To target one host:

tracedecay install --agent claude
tracedecay install --agent codex
tracedecay install --agent cursor
tracedecay install --agent devin
tracedecay install --agent gemini
tracedecay install --agent hermes

Project-local setup:

tracedecay install --local --agent cursor
tracedecay install --local --agent codex
tracedecay install --local --agent devin

After setup, restart the agent so it loads the MCP server, plugin, hooks, or rules written for that host.

Codex first-time installs drive codex plugin add tracedecay@personal themselves. Trust new command hooks inside Codex with /hooks, then start a new session so the installed cache is loaded.

Common Commands

tracedecay init [path]              # enroll a project and publish its first generation
tracedecay sync [path]              # explicit administrative refresh
tracedecay sync --force [path]      # explicit full generation refresh
tracedecay status [path]            # graph stats, freshness, savings, cost
tracedecay tool                     # list every MCP tool
tracedecay tool search "<query>"    # CLI symbol search
tracedecay tool files               # indexed files
tracedecay tool affected --args -   # impacted tests/files ({"files":[...]})
tracedecay serve                    # MCP server
tracedecay doctor                   # read-only installation health check
tracedecay dashboard [--open]       # local dashboard
tracedecay monitor                  # live MCP savings/cost TUI
tracedecay update                   # refresh binary, plugins, daemon
tracedecay upgrade                  # self-upgrade current channel

Every MCP tool is reachable from the shell as tracedecay tool <name>; there are no separate per-tool subcommands. Run tracedecay tool for the grouped list and tracedecay tool <name> --help for one tool's parameters.

Agent Tools

The MCP server exposes tools grouped around normal coding workflows:

• Discovery: tracedecay_context, tracedecay_search, tracedecay_outline, tracedecay_files
• Graph traversal: tracedecay_callers, tracedecay_callees, tracedecay_impact, tracedecay_affected
• Code health: tracedecay_complexity, tracedecay_dead_code, tracedecay_unmounted_files, tracedecay_coupling, tracedecay_test_risk
• Git workflow: tracedecay_diff_context, tracedecay_pr_context, tracedecay_changelog, tracedecay_test_map
• Editing: tracedecay_str_replace, tracedecay_multi_str_replace, tracedecay_insert_at, tracedecay_ast_grep_rewrite
• Memory: exact tracedecay_fact_store_add|search|probe|related|reason|contradict|get|update|remove|list routes, plus tracedecay_fact_feedback and tracedecay_memory_status

Most read tools are safe to call in parallel. Edit tools are single-file, anchored, and re-index after writing.

Index Freshness

The daemon owns freshness and background convergence. Hooks, MCP, LSP, and workspace events submit bounded, content-free hints; the daemon resolves exact repository/worktree/ref/commit identity, captures a snapshot, and publishes an immutable generation. Queries report the generation and typed warming/refresh_required/partial/unavailable coverage while a newer generation is being prepared; they never run a hidden sync or silently use an ancestor. An explicit tracedecay sync remains an administrative refresh request for diagnostics or offline workflows.

Linked git worktrees share one registered project authority through the repository common directory. Initialize once from any checkout; do not copy a TraceDecay store into another worktree. Queries and comparisons select exact worktree/ref/commit generations and report typed stale, indexing, partial, or unavailable state when that snapshot is not ready. Branches and worktrees do not create separate databases or fact stores.

See docs/V2-OPERATING-MODEL.md for branch selection, provenance, and recovery behavior.

Dashboard

tracedecay dashboard
tracedecay dashboard --port 8080
tracedecay dashboard --port 0 --open

The dashboard includes graph exploration, project memory, LCM session search, token savings, and cost views. See docs/dashboard.md.

Privacy

Core indexing, graph queries, MCP tools, memory, and dashboard data use the local daemon-owned authority by default. That default does not mean every command is offline: configured remote sources and authorities can exchange only authorized, sanitized, classified records under their remote policy.

Network-capable effects are separate from core retrieval:

• Worldwide counter: when opted in, sends the pending aggregate token-savings amount and may fetch the public total/country display data.
• GitHub release checks and updates: contact GitHub release endpoints. An explicitly configured private GitHub review source can use a read-only credential from the operating-system keyring; missing, ambiguous, write-capable, or unverifiable credentials fail closed.
• Provider usage and pricing: tracedecay cost performs a side-effect-free read over immutable native usage observations and the deterministic bundled all-provider pricing table. Unknown or unavailable evidence remains typed.
• Semantic models: when semantic auto-download is enabled, TraceDecay can download missing revision-pinned artifacts from Hugging Face hosts and verify their catalog-pinned lengths and SHA-256 digests before publication.
• Configured remote authority: an authenticated, policy-authorized peer can perform remote retrieval, replication, backup, restore, or failover. This path fails closed with typed unavailable, denied, or stale-peer state.

These services receive normal transport metadata, including the connection's source address, in addition to any request payload. The counter request is an aggregate amount, not repository content, but it is not an anonymity guarantee. Use a network policy or firewall if a command must make no outbound connection. An opt-out, denial, timeout, or unavailable remote service must remain visible as that state; it is not evidence of a zero counter, an up-to-date release, or current pricing. See Security for the complete outbound-access and credential boundary.

Disable the worldwide counter with:

tracedecay disable-upload-counter

Troubleshooting

tracedecay doctor
tracedecay status --json

tracedecay doctor is read-only installation and authority diagnostics. It does not repair stores or rewrite host files; authorized maintenance is a separate daemon operation with its own preview, receipt, and recovery state.

Common fixes:

• Not initialized: run tracedecay init from the project root.
• Agent does not see tools: run tracedecay doctor, then restart the agent.
• Missing symbols: inspect tracedecay status --json for the selected generation and typed warming/refresh-required coverage; request an explicit administrative refresh only when the daemon says it is needed, then confirm the file is not ignored.
• Slow first index: use daemon status/coverage to inspect warming and backlog; routine updates are daemon-owned.

Build

Building from a source checkout requires Node.js 22+ and npm in addition to Rust: dashboard/app-dist/ is generated output and is not committed, so build.rs runs npm ci and npm run build in dashboard/ before embedding the UI. Release users should install the prebuilt, checksummed GitHub archive; workspace Cargo packages are private.

cargo build --release
cargo build --release --features medium
cargo build --release --no-default-features

cargo nextest run --workspace --all-features --no-fail-fast
cargo check --no-default-features
cargo clippy --workspace --all-targets

Docs

• User guide
• Comparable tools
• Dashboard
• V2 operating model
• V2 roadmap

Origin

TraceDecay is a Rust port of the original CodeGraph TypeScript implementation by @colbymchenry.

License

MIT License -- see LICENSE.