github.com/ScriptedAlchemy/tracedecay @v0.0.32

Semantic Code Intelligence for AI Coding Agents

Fewer tokens • Fewer tool calls • 100% local

Why tracedecay?

AI coding agents waste tokens exploring codebases. Every grep, glob, and file read costs money. On complex tasks, agents spawn multiple Explore sub-agents that scan hundreds of files just to build context.

tracedecay gives agents a pre-indexed semantic knowledge graph. Instead of scanning files, the agent queries the graph and gets instant, structured answers -- the right symbols, their relationships, and source code, in one call.

How It Works

┌──────────────────────────────────────────────────────────────┐
│  AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)   │
│                                                              │
│  "Implement user authentication"                             │
│        │                                                     │
│        ▼                                                     │
│  ┌─────────────────┐       ┌─────────────────┐               │
│  │  Sub-agent      │ ───── │  Sub-agent      │               │
│  └────────┬────────┘       └─────────┬───────┘               │
└───────────┼──────────────────────────┼───────────────────────┘
            │                          │
            ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│  tracedecay MCP Server                                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Search    │  │   Callers   │  │   Context   │           │
│  │   "auth"    │  │  "login()"  │  │   for task  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌───────────────────────┐                       │
│              │   libSQL Graph DB     │                       │
│              │   • Instant lookups   │                       │
│              │   • FTS5 search       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Without tracedecay: Agents use grep, glob, and Read to scan files -- many API calls, high token usage.

With tracedecay: Agents query the graph via MCP tools -- instant results, local processing, fewer tokens.

Key Features

Quick Start

1. Install

Homebrew (macOS):

brew install ScriptedAlchemy/tap/tracedecay

Scoop (Windows):

scoop bucket add tracedecay https://github.com/ScriptedAlchemy/scoop-bucket
scoop install tracedecay

Note: The Homebrew tap and Scoop bucket are external repositories updated separately from this one — until they pick up the rename, the package may still be published under the legacy package name.

Cargo (any platform):

cargo install tracedecay                          # full (50+ languages, default)
cargo install tracedecay --features medium        # medium tier
cargo install tracedecay --no-default-features    # lite (smallest binary)

Prebuilt binaries (Linux, Windows, macOS):

Download from the latest release and place the binary in your PATH.

2. Configure your agent

tracedecay install                         # auto-detects installed agents
tracedecay install --agent antigravity     # Google Antigravity (formerly Windsurf)
tracedecay install --agent claude          # Claude Code
tracedecay install --agent cline           # Cline
tracedecay install --agent codex           # OpenAI Codex CLI
tracedecay install --agent codex --automation
tracedecay install --agent copilot         # GitHub Copilot
tracedecay install --agent cursor          # Cursor
tracedecay install --agent gemini          # Gemini CLI
tracedecay install --agent hermes          # Hermes Agent
tracedecay install --agent hermes --profile work
tracedecay install --agent kilo            # Kilo CLI
tracedecay install --agent kiro            # AWS Kiro
tracedecay install --agent kimi            # Moonshot Kimi CLI
tracedecay install --agent opencode        # OpenCode
tracedecay install --agent roo-code        # Roo Code
tracedecay install --agent vibe            # Mistral Vibe
tracedecay install --agent zed             # Zed

Each agent gets the integration that matches its host:

• Claude Code: MCP config, PreToolUse/UserPromptSubmit/Stop hooks, CLAUDE.md prompt rules, and auto-allowed tool permissions.
• Kiro: global MCP config, tracedecay.md steering loaded as a resource, and a tracedecay-managed default agent with delegation guardrails and post-write sync. User-managed Kiro agents are preserved.
• Codex: a Codex plugin bundle for MCP, hooks, and skills through Codex's source, marketplace, and installed-cache flow. The installer does not write ~/.codex/AGENTS.md or ~/.codex/hooks.json.
• Hermes: a native profile plugin, tracedecay memory provider, and tracedecay LCM context engine with native lcm_* session tools backed by tracedecay_lcm_* MCP tools.
• Cursor: a local plugin in ~/.cursor/plugins/local/tracedecay that bundles MCP, hooks, and the tracedecay rule with commands rewritten to the resolved absolute tracedecay executable path.

All changes are idempotent -- safe to run again after upgrading. After agent setup, you'll be offered a global git post-commit hook.

Managed skills generated by the self-improvement loop are exported through the host surface that each provider can load safely:

The curation backend is provider-agnostic. Hermes remains a compatibility bridge and reference source; TraceDecay automation can delegate intelligence to hosts such as the Codex app server without requiring Hermes to run.

For project-scoped setup, run from the repository root:

tracedecay install --local --agent cursor

Local install writes only workspace files such as .mcp.json, .vscode/mcp.json, .hermes/plugins/tracedecay/, or the equivalent project config or plugin files for Claude, Codex, Gemini, Hermes, Kiro, OpenCode, Copilot/VS Code, Zed, Roo Code, Kimi, Kilo, and Vibe. Generated MCP configs and plugin wrappers use the resolved absolute tracedecay executable path.

Hermes installs into ~/.hermes/plugins/tracedecay/ by default, or into ~/.hermes/profiles/<name>/plugins/tracedecay/ with --profile <name>. Profile names are normalized to lowercase and must match [a-z0-9][a-z0-9_-]{0,63}. The generated context engine resolves its project from explicit host kwargs first, then a project_root key on the Hermes config object, then the install-time pin, and finally the session cwd.

Pin a profile to one project with tracedecay install --agent hermes [--profile <name>] --project-root /abs/path. The pin is written into the generated plugin, applies to every plugin tool call regardless of the Hermes working directory, and survives later unpinned reinstalls. Use tracedecay uninstall --agent hermes --profile <name> to remove a named profile install; reinstall and doctor --agent hermes currently operate on the default profile.

To refresh generated plugin code after an upgrade without any config writes, run tracedecay update-plugin (alias update-plugins). It rewrites only tracedecay-generated artifacts: the Hermes plugin files and dashboard page for every detected profile, the Cursor plugin bundle, the Codex plugin bundle, and the Kiro managed agent. It re-reads Hermes pins from config.yaml, never writes them, and leaves config.yaml, config.toml, mcp.json, settings, hooks, and prompt rules byte-for-byte intact. Config-managed integrations (Claude, Gemini, ...) have no generated artifacts and are reported as untouched; tracedecay reinstall remains the command that reconciles their config entries.

Hermes wrappers run from Hermes' current working directory, use a 600-second timeout, and include truncated stdout/stderr in error JSON. Hermes local install without --profile writes only project plugin files and .hermes/config.yaml; tracedecay install --local --agent hermes --profile <name> is a deliberate mixed-scope mode that targets the named profile instead. Project-local Hermes plugins are loaded by launching Hermes with HERMES_HOME=<project>/.hermes.

For Codex install details, see Codex plugin installs. For Cursor, both global and --local install put the plugin in ~/.cursor/plugins/local/tracedecay and require a Cursor reload. The plugin MCP config runs tracedecay serve --path ${workspaceFolder}, so it resolves the active workspace instead of the plugin directory and uses that workspace's active project store rather than the legacy global Cursor MCP registration. Cursor install no longer writes .cursor/mcp.json, .cursor/hooks.json, .cursor/rules/tracedecay.mdc (legacy artifact name), or .cursor/permissions.json; approvals are left to Cursor approval/run-mode behavior. The plugin hooks are:

• sessionStart — fire-and-forget; injects context steering the Agent toward tracedecay MCP tools and reports index freshness (suggests tracedecay init when no initialized project store is found).
• postToolUse (unmatched — Cursor's docs enumerate no matcher value for semantic search) — fail-open; injects a soft additional_context hint after broad search/read tools (Grep, Glob, Read, semantic search, shell rg) so Cursor switches to tracedecay_grep, tracedecay_context, tracedecay_search, tracedecay_outline, or tracedecay_files.