TraceDecay User Guide

Thanks for downloading TraceDecay!

TraceDecay is a code intelligence tool that builds a semantic knowledge graph of your codebase. It gives AI coding agents (like Claude Code) instant, structured access to your code's symbols, relationships, and dependencies, so they spend fewer tokens scanning files and more time writing code.

Core indexing and retrieval run through the local daemon by default. Configured remote sources and authorities are separate, policy-bound effects; see Privacy and Network before assuming an offline-only deployment.

Final V2: tracedecay-graph-db is the sole Grafeo boundary. Incompatible persisted data returns ResetRequired and requires explicit reset or recreation. Storage, scope, and lossless retrieval rules are in the V2 operating model.

Installing TraceDecay
Your First Index
Connecting to Your Agent
Exploring Your Codebase from the CLI
Keeping the Index Fresh
Checking Your Setup with Doctor
Finding Affected Tests
MCP Tools for AI Agents
Supported Languages
Privacy and Network
Updating TraceDecay
Configuration Files
Troubleshooting

Installing TraceDecay

Pick whichever method suits your platform.

Linux and Apple silicon macOS:

curl -fsSL https://raw.githubusercontent.com/ScriptedAlchemy/tracedecay/master/install.sh | bash

The installer verifies the archive's build-provenance attestation with the GitHub CLI (gh attestation verify), so gh must be installed and signed in (gh auth login). Without gh it refuses, because the release's SHA256SUMS sits beside the archive in the same release and proves only that the download is intact, not who built it. To install on that checksum alone, set TRACEDECAY_INSTALL_UNATTESTED=1; the installer then warns that provenance was not verified. Later tracedecay upgrade runs verify the attestation themselves and need no gh.

To verify a downloaded archive by hand:

gh attestation verify tracedecay-beta-<tag>-<platform>.tar.gz --repo ScriptedAlchemy/tracedecay \
  --signer-workflow ScriptedAlchemy/tracedecay/.github/workflows/release-beta.yml

Stable archives (tracedecay-<tag>-<platform>) are signed by .github/workflows/release.yml.

Windows:

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

Prebuilt binaries:

Download from the latest release and place the binary somewhere on your PATH. Archives are available for macOS (Apple Silicon), Linux (x86_64 and ARM64), and Windows (x86_64).

Your First Index

Start the daemon first, then enroll the project:

tracedecay daemon install-service
cd /path/to/your/project
tracedecay init

tracedecay init is brokered through the daemon-owned code-index scheduler. With no daemon accepting connections for this profile it refuses before it writes anything:

Error: project route error (code_index_scheduler_unavailable): project initialization requires the daemon-owned code-index scheduler; start the daemon and retry

Confirm the daemon with tracedecay daemon status and re-run init.

TraceDecay enrolls the repository with the daemon, captures an exact checkout snapshot, and publishes a validated code generation. Project facts, sessions, and lossless LCM remain project-wide; code generations retain exact repository, checkout, worktree, ref, commit/tree, snapshot, and generation provenance. Storage is daemon-owned (an explicit local .tracedecay/ install is only a location choice), and clients never open a project database directly.

Once it finishes, run tracedecay status to see what was indexed:

tracedecay status

This prints an overview of your project: the number of files, symbols, edges (relationships between symbols), language distribution, and how many tokens the index has saved you so far. If you just want the summary line without the ASCII art, pass --short:

tracedecay status --short

For machine-readable output, use --json.

Why `init` is explicit and refresh is daemon-owned

tracedecay init is the one-time enrollment and first-generation operation. After enrollment, hooks, MCP, LSP, and the daemon's bounded freshness ladder submit content-free hints. The daemon reconciles native Git state, captures the selected worktree snapshot, and publishes a complete generation in the background. Queries continue serving the last complete generation while a refresh is warming and report typed refresh_required, warming, partial, or unavailable coverage when appropriate.

Linked git worktrees do not need their own tracedecay init. They resolve to the same registered project authority while each code generation retains exact worktree/ref/commit/snapshot identity. Facts, sessions, and LCM remain owned by that project authority; branch and worktree labels are provenance only.

An explicit tracedecay sync remains an administrative refresh request for a diagnostic or offline workflow; it is not the normal post-edit product path and never opens a store outside the daemon.

Incremental convergence

The daemon reconciles only the bounded changed set from each hint and reuses unchanged content-addressed artifacts when their complete identity matches. Duplicate hints and no-op saves produce no new durable work. A failed or cancelled refresh leaves the prior complete generation readable.

If an authenticated derived lexical cursor no longer fits its sealed source, the daemon discards only that resumable text-artifact staging database and rebuilds it automatically. Project identity, sessions, memory, configuration, the sealed source generation, and any prior complete serving generation remain untouched. Run tracedecay sync, then re-check tracedecay status; do not use storage reset-project-store, which is reserved for a reported schema reset requirement.

What gets indexed

The code index is Git's view of the worktree: tracked files and untracked files that .gitignore does not ignore. Ignored files are never indexed. From that set, the project's index.exclude.v1 patterns remove paths, and index.include.v1 patterns re-admit paths the exclude list would remove. The shipped exclude list skips generated, vendored, and cache directories such as node_modules, vendor, dist, build, target, coverage, .next, .turbo, .cache, virtualenvs, and __pycache__, plus minified *.min.* assets.

A pattern is a glob over the project-relative path: * and ? stay inside one path segment, ** spans segments, and a pattern that names a directory covers everything under it (docs and docs/** are equivalent). A pattern without a slash matches only at the project root; write **/docs to match the directory at any depth. grep, ast_grep_search, and unmounted_files walk the same filtered file set.

Both settings are project-scoped and apply when the daemon restarts; the next generation then adds or drops exactly the matching files. Change them from the dashboard Settings page or with tracedecay_configuration_set (value kind string_list), for example to also skip a fixtures tree:

tracedecay tool configuration_set --args '{"layer":{"kind":"project","project_id":"<id>"},"key":"index.exclude.v1","value":{"kind":"string_list","value":["vendor/**","**/node_modules/**","generated-fixtures/**"]},"expected_revision":"<revision>","idempotency_key":"<key>"}'

The value replaces the whole list, so start from the current effective value (tracedecay tool configuration_get --args '{"key":"index.exclude.v1"}'). A malformed pattern is refused before anything is written. There is no per-run folder exclusion; init and sync take no folder flags.

Seeing what changed

Use the daemon's status/coverage result to see the selected generation, exact snapshot provenance, changed/reused counts, and warming/backlog state. Doctor is a read-only health diagnostic; changes require a separate authorized daemon operation with its own preview and receipt.

Diagnosing slow daemon convergence

If status reports warming or a backlog, inspect the daemon's typed coverage first. When the daemon reports that an administrative refresh is appropriate, request one; --verbose (-v) also prints the daemon's admission receipt:

tracedecay sync --verbose

Example output:

{
  "reconcile_scope": "authoritative_project",
  "status": "queued",
  "project_root": "/path/to/repo"
}
code-index reconciliation queued via daemon for /path/to/repo

The request only queues the reconcile; follow its progress with tracedecay status.

Nothing to add to .gitignore

TraceDecay never creates files inside your repository's working tree, so init leaves git status untouched and nothing needs a .gitignore entry: all project data lives under ~/.tracedecay, and a git repository additionally carries an identity marker inside .git/ (never committed). If a project was enrolled by an older TraceDecay, it may still have a leftover .tracedecay/enrollment.json in the repository. Nothing reads that file any more; identity comes from .git/ and the profile registry, so you can safely delete the .tracedecay/ directory.

Connecting to Your Agent

TraceDecay works as an MCP (Model Context Protocol) server. AI coding agents connect to it to query your codebase instead of scanning files directly. The install command sets everything up automatically.

Claude Code

tracedecay install

Claude Code owns marketplace registration, enabled state, cache, hook trust, and permissions. When activation is missing, TraceDecay stages verified source and prints the native activation command without writing a lifecycle receipt. After that host-native action, run the install again so TraceDecay can atomically record the catalog component set. The plugin bundles the MCP server, lifecycle hooks, subagents, skills, and slash commands. tracedecay update-plugin refreshes receipt-owned source only through the same component transaction. TraceDecay does not migrate or rewrite Claude's host config. The installed hooks submit bounded native lifecycle envelopes only: SessionStart, Stop, and saved-edit PostToolUse (Edit|MultiEdit|Write|NotebookEdit). The daemon owns all later capture, indexing, staleness checks, compaction, and advisory work; a hook never routes tools, reads a store, or starts a model.

Other agents

TraceDecay has receipt-backed profile-wide install lifecycles for these agents:

tracedecay install --agent claude      # Claude Code (default)
tracedecay install --agent opencode    # OpenCode
tracedecay install --agent codex       # OpenAI Codex CLI
tracedecay install --agent gemini      # Gemini CLI
tracedecay install --agent hermes      # Hermes Agent
tracedecay install --agent copilot     # GitHub Copilot CLI
tracedecay install --agent cursor      # Cursor
tracedecay install --agent devin       # Devin
tracedecay install --agent kiro        # AWS Kiro
tracedecay install --agent kimi        # Kimi Code CLI
tracedecay install --agent chatgpt     # ChatGPT

Other host integrations can be detected by doctor, but do not appear in the installer until they have a canonical first-party component route.

Each installed agent gets the profile-wide configuration its host supports: MCP registration or native plugin tools, with permissions where available.

Hermes installs one native user plugin through Hermes' plugin API.
Cursor installs a local plugin in ~/.cursor/plugins/local/tracedecay that bundles MCP, hooks, and the tracedecay rule.
Devin registers the tracedecay serve stdio MCP server in ~/.config/devin/mcp_config.json, preserving other Devin MCP entries and leaving Devin's permission policy unchanged.
Codex uses Codex's plugin source, marketplace, and installed-cache flow: TraceDecay stages the source bundle and marketplace entry, then drives codex plugin add tracedecay@personal to install Codex's cache from that source. The plugin owns MCP, hooks, and skills. TraceDecay does not write ~/.codex/AGENTS.md, ~/.codex/hooks.json, or [hooks.state] trust hashes. Codex still asks you to trust new command hooks via /hooks.
Kimi Code CLI stages its plugin source at ~/.tracedecay/host-bundle-stage/kimi/tracedecay; for the first install, run the printed /plugins install <staged-path> command in Kimi Code (it asks you to trust the plugin), then rerun TraceDecay so it can record the staged source. Later installs and updates refresh that plugin without a Kimi step: TraceDecay briefly starts kimi web on a loopback port and asks Kimi's own installer to reinstall it. Kimi owns ~/.kimi-code/plugins/installed.json and its managed/cache paths.
ChatGPT stages its portable plugin bundle at ~/.tracedecay/host-bundle-stage/chatgpt/tracedecay. Successful staging exits 0; registration inside ChatGPT is reported as unverifiable with installation guidance. uninstall --agent chatgpt removes the receipt-owned staged bytes. The same explorer is also included in the local Codex plugin, which launches it over stdio.

Hermes setup writes the single user integration to ~/.hermes/plugins/tracedecay/ and enables it in ~/.hermes/config.yaml under plugins.enabled. install, update-plugin, reinstall, doctor, and uninstall all target that same integration. Hermes may use its own home for host-owned config, plugins, and transcripts, but named Hermes profiles, project-local .hermes directories, and HERMES_HOME never select a TraceDecay installation, store, or project identity.

The plugin registers one Hermes-native wrapper per tracedecay tool, adds a lightweight pre_llm_call steering hook, registers a /tracedecay_status slash command when the installed Hermes version supports plugin commands, and bundles a tracedecay:tracedecay plugin skill. It also registers a tracedecay memory provider (holographic facts via exact fact tools / fact_feedback / memory_status) and a tracedecay context engine that compresses long conversations through the daemon's session authority. Project-attached sessions and lossless LCM are project-wide; untethered user sessions remain profile-wide. The context engine exposes native lcm_grep, lcm_load_session, lcm_describe, lcm_expand, lcm_expand_query, lcm_status, and lcm_doctor tools (backed by the tracedecay_lcm_* MCP tools) and uses the same daemon-routed session authority as every other host. The wrappers call tracedecay tool <name> --json --args <json> with a real project root from the host context or working directory when available, with a 600-second timeout and truncated stdout/stderr in error JSON. Hermes configuration paths remain host-owned inputs for plugin behavior; they never become TraceDecay storage identities. Removed Hermes install flags (--profile, --all-profiles, and --project-root) and removed MCP routing fields (storage_scope and hermes_home) are errors, not compatibility aliases.

Verifying Hermes plugin and context-engine changes

When changing generated Hermes plugin or context-engine behavior, start with TraceDecay's read-only analysis tools before rebuilding or reinstalling anything: use tracedecay_diff_context to inspect modified symbols, dependencies, and affected tests; use tracedecay_complexity, tracedecay_dead_code, and tracedecay_coupling for focused quality checks; tracedecay_test_risk for untested hot spots; tracedecay_diagnostics for structured compiler/type feedback; and tracedecay_run_affected_tests for the focused test set when test execution is appropriate. Each managed run is recorded in the project session store against the session its request names (session_id), with its start and finish times, exit status, and passed/failed/ignored counts; tracedecay_test_results reads that record back, and the dashboard's Loom view draws it on the session's lane. A run whose request names no session is recorded unattributed.

For LCM/session issues, pair tracedecay_lcm_status with the read-only LCM diagnostics (tracedecay_lcm_doctor, or the native Hermes lcm_doctor wrapper). Inspect reported retention, payload, provenance, and coverage states. Authorized retention and maintenance effects are separate daemon operations with their own previews, confirmations, and receipts; the diagnostic path never applies them.

Known Hermes API caveats: native lcm_* tool dispatch receives messages=messages, but direct registered live-ingest tools should remain gated unless the host explicitly forwards messages. The context_engine_tool_handlers_receive_messages flag is a TraceDecay convention, not stock Hermes API. Treat compression.* as built-in compressor config; only compression.enabled gates auto-compaction globally.

Kiro setup registers the profile-wide tracedecay MCP server by editing Kiro's documented ~/.kiro/settings/mcp.json; it never runs kiro-cli, so it works whether or not kiro-cli is installed or signed in. It does not create steering files, custom agents, default-agent settings, hooks, or workspace MCP registrations. See Kiro integration for the exact lifecycle.

The install is idempotent, safe to run again after upgrading tracedecay. You'll also be offered the option to set up an optional global git post-commit hint hook (more on that below).

Profile-wide installs

Each install writes or stages the active profile's host integration; it does not create per-repository host configuration. The host's workspace/session context selects the active TraceDecay project at runtime.

Devin supports both profile-wide and project installation:

tracedecay install --agent devin
tracedecay install --local --agent devin

The first command writes Devin's user MCP registry at ~/.config/devin/mcp_config.json. The second writes the repository's .devin/mcp_config.json. Both register the exact stdio entry accepted by Devin's mcp add command: the resolved tracedecay executable, serve as its argument, and transport: "stdio". Existing Devin MCP servers and unrelated configuration remain intact. Restart Devin after installing, updating, or removing the integration. See Devin integration for the config locations and lifecycle details.

Cursor install is plugin-based:

tracedecay install --agent cursor installs cursor-plugin/ into ~/.cursor/plugins/local/tracedecay.
The plugin MCP config runs tracedecay serve with no --path: Cursor spawns plugin MCP servers with the workspace folder as the working directory and never expands ${workspaceFolder} for them, so serve resolves the active workspace's project store from its cwd and MCP initialize roots. An unenrolled workspace still completes the MCP handshake; tool calls answer with a typed project_not_enrolled error until tracedecay init runs there (details in the plugin's README.md).
Cursor install no longer writes .cursor/mcp.json, .cursor/hooks.json, .cursor/rules/tracedecay.mdc, or .cursor/permissions.json; approvals are left to Cursor approval/run-mode behavior.
The Cursor plugin's daemon-owned native lifecycle journey uses sessionStart, preCompact, afterFileEdit, and stop. Each hook is fail-open; only sessionStart can return immediate additional_context. Cursor's beforeSubmitPrompt contract cannot inject model context, so TraceDecay does not install it. The daemon owns transcript capture, indexing, compaction, branch/preflight work, and advisory delivery. Manual or external-terminal changes are still best covered by the git post-commit hook and on-demand MCP staleness checks.

Manual Cursor plugin install for local development:

mkdir -p ~/.cursor/plugins/local
ln -s /path/to/tracedecay/cursor-plugin ~/.cursor/plugins/local/tracedecay

Reload Cursor after installing or replacing the plugin. The plugin expects the tracedecay binary to be available on PATH; ensure your shell PATH resolves the intended installed binary.

Codex global install is plugin-based for MCP, hooks, and skills. TraceDecay stages the plugin source bundle and marketplace entry, then drives codex plugin add tracedecay@personal so Codex copies the source into ~/.codex/plugins/cache/personal/tracedecay/<version> and records [plugins."tracedecay@personal"] enabled = true. First install writes ~/.codex/plugins/tracedecay/ and ~/.agents/plugins/marketplace.json. tracedecay update-plugin --agent codex is owned by the receipt-backed component-set transaction, which restages the source and drives plugin add again.

Skill visibility follows Codex's plugin model. codex plugin list and codex plugin add inspect the marketplace source bundle. Active Codex sessions load skills, MCP config, and bundled hooks from the installed cache, not directly from ~/plugins/tracedecay; start a new Codex session after adding the plugin or recopying it. Codex also skips new or changed command hooks until you trust them, so run /hooks inside Codex after install or recopy.

Current Codex limitations: TraceDecay drives codex plugin add / remove but cannot reload an active Codex session or trust plugin command hooks for you (use /hooks after install or recopy). Uninstall drives codex plugin remove tracedecay@personal and then removes the staged source. The legacy Codex config surfaces are intentionally left alone.

Kimi's first global install is also two-step: TraceDecay stages source, then Kimi Code's /plugins install <staged-path> registers it after Kimi's trust prompt. Once Kimi lists the TraceDecay plugin as installed and enabled from exactly that staged path, tracedecay update, update-plugin, and a repeated install --agent kimi refresh it themselves. TraceDecay starts kimi web --no-open --port <ephemeral> (loopback only, with Kimi's auto-update disabled), authenticates with Kimi's server token from ~/.kimi-code/server.token, calls POST /api/v1/plugins with the staged path, accepts the refresh only when Kimi reports the staged version in state ok, and stops the server it started. A missing kimi, an older Kimi without kimi web, a refused token, a timeout, or any other answer leaves the /plugins install <staged-path> step pending and prints why. To remove it, use Kimi Code's /plugins remove tracedecay first, then rerun tracedecay uninstall --agent kimi to remove the staged source. TraceDecay never writes Kimi's managed plugin directory or installed.json; only Kimi's installer does.

ChatGPT registers plugins inside its own interactive surfaces. TraceDecay stages the portable bundle and reports the host registration as unverifiable, with informational guidance rather than a standing pending action. Successful install, update-plugin, and update exit 0; doctor checks the staged bytes and fails incomplete or damaged staging. uninstall --agent chatgpt removes the receipt-owned staged tree; host-side removal is performed inside ChatGPT. The local Codex plugin includes the same code explorer and launches it over stdio.

The generated MCP entries use the resolved absolute path to the current tracedecay executable.

Config edits

Whenever tracedecay rewrites an agent config file, on install, on uninstall, or an explicitly authorized host-maintenance operation, it edits only its own entries and publishes the result atomically. It never leaves backup or "original" copies beside host configs. Uninstall removes TraceDecay's entries and leaves every other setting in place. Doctor only reports configuration findings and never rewrites hooks.

Removing an integration

tracedecay uninstall                   # remove Claude Code integration
tracedecay uninstall --agent codex     # remove Codex integration
tracedecay uninstall --agent hermes

Exploring Your Codebase from the CLI

You don't need an AI agent to use tracedecay. Every MCP tool is reachable from the shell through tracedecay tool <name>, which dispatches the same tool the agent would call. There are no separate per-tool subcommands, tracedecay query, tracedecay context, tracedecay files, and tracedecay affected do not exist and will fail with an unrecognized-subcommand error.

tracedecay tool                        # every tool, grouped
tracedecay tool search --help          # one tool's parameters

Tool names work with or without the tracedecay_ prefix, and dashes and underscores are interchangeable (dead-code == dead_code). --json prints the raw payload instead of the human rendering.

Searching for symbols

tracedecay tool search "authenticate"

This searches the index for symbols matching your query. It returns function names, class names, method names, and their file locations and signatures. Limit results with --limit:

tracedecay tool search "authenticate" --limit 5

Building task context

tracedecay tool context "implement user authentication"

This is the same context builder that AI agents use. Given a natural language task description, it finds the most relevant entry points, related symbols, and code structure. Output defaults to the human text rendering. --json prints the MCP tool result every tool prints: the rendered content, isError, and structuredContent holding the whole typed result (or a refusal's typed problem record). --format json prints only the typed result.

tracedecay tool context "implement user authentication" --json --max-nodes 30

The --max-nodes flag controls how many symbols are included (default: 20).

Listing indexed files

tracedecay tool files                           # all files
tracedecay tool files --path src/mcp            # only files under src/mcp/
tracedecay tool files --pattern "**/*.rs"       # only Rust files
tracedecay tool files --json                    # tool result; typed payload in structuredContent

Running the MCP server directly

tracedecay serve

This starts the MCP server over stdio. You normally don't need to run this yourself, the agent integration handles it. But it's useful for debugging or connecting custom tools.

Working from a subdirectory

You can open your AI agent from any subdirectory of an enrolled project. TraceDecay resolves the registered project and exact worktree through the daemon; it does not choose a database by walking to the nearest path.

When the MCP server starts from a subdirectory, listing tools like tracedecay_files, tracedecay_search, and tracedecay_context automatically scope their results to that subdirectory while retaining the project/worktree identity resolved by the daemon. This is useful in monorepos or large projects where you want to focus on one area.

Graph traversal tools (tracedecay_callers, tracedecay_callees, tracedecay_impact, etc.) remain unscoped so you can still follow connections across directory boundaries.

You can always override the automatic scope by passing an explicit path parameter to any tool. tracedecay_status shows the active scope prefix when one is in effect.

Keeping the Index Fresh

The daemon owns freshness and convergence. Hooks, MCP, LSP, and workspace events submit bounded, content-free hints; the daemon coalesces them, resolves the exact repository/worktree/ref/commit state with native Git, and publishes a validated generation. Exact, lexical, and graph queries remain available from the last complete generation while semantic or newer work is warming.

Every freshness-sensitive result reports the generation/snapshot it used and typed coverage such as warming, refresh_required, partial, or unavailable. A backlog or unavailable daemon is visible state, not a reason to silently use an ancestor branch or return an empty success.

Host change hints

During tracedecay install, supported hosts can send post-edit, stop, commit, or workspace hints to the daemon. Hints are non-blocking and contain no source payload. They never open a TraceDecay database or run a branch tracking command.

You can also set it up manually:

Global (all repos):

git config --global core.hooksPath ~/.git-hooks
mkdir -p ~/.git-hooks
cp scripts/post-commit ~/.git-hooks/post-commit
chmod +x ~/.git-hooks/post-commit

Per-repo:

cp scripts/post-commit .git/hooks/post-commit
chmod +x .git/hooks/post-commit

MCP freshness checks

MCP calls perform a bounded freshness check and report the selected generation or a typed warming/refresh-required state. They do not run an implicit refresh or open storage. Hooks and the daemon scheduler own background convergence; multiple clients are serialized by the daemon authority.

Daemon service

The daemon is required, not optional: tracedecay init brokers through the daemon-owned code-index scheduler, and the read commands connect to the daemon rather than starting one. Install the per-user service so it survives terminal sessions and logout:

tracedecay daemon install-service
tracedecay daemon status

On Linux this installs a systemd user service. On macOS this installs a LaunchAgent at ~/Library/LaunchAgents/com.tracedecay.daemon.plist. On Windows this registers a least-privilege, per-user Task Scheduler task that starts at logon. The task name and ACL are scoped to the current Windows SID, and the daemon endpoint is an authenticated loopback connection discovered from the selected profile.

The service is memory-bounded, sized from physical RAM when it is installed: MemoryMax is half of RAM up to 24 GiB, MemoryHigh is three quarters of that, and MemorySwapMax is an eighth of it (on a 128 GiB host: 18 GiB, 24 GiB, and 3 GiB). MemoryHigh is the line where the daemon refuses new growth and sheds reclaimable caches; MemoryMax is the kernel kill line, after which the unit restarts. Override them with a drop-in, which reinstalls leave alone:

systemctl --user edit tracedecay
# [Service]
# MemoryHigh=12G
# MemoryMax=16G
# MemorySwapMax=2G

launchd has no enforced memory ceiling, so the LaunchAgent passes the same MemoryMax budget to the daemon as TRACEDECAY_RESIDENT_MEMORY_LIMIT_BYTES, where it bounds admission and triggers the same cache shedding.

Use tracedecay daemon start, stop, or restart for explicit lifecycle control. Remove the service with:

tracedecay daemon uninstall-service

Install without activation with tracedecay daemon install-service --no-start. Updates and post-update maintenance preserve the exact captured service state: running services return to running, stopped-enabled services stay stopped and enabled, stopped-disabled services stay stopped and disabled, and masked or missing services remain untouched. Passive commands and integrations (status, doctor, tool, serve, MCP proxying, and hooks) never start or enable the service. If the daemon is unavailable, it may be intentionally held; report the typed state instead of retrying or changing lifecycle. Use start or restart only when you intentionally want the daemon running.

CLI-Only Workflows

If you don't keep an agent attached, install the supported daemon service and optional Git hint hook:

cp scripts/post-commit .git/hooks/post-commit
chmod +x .git/hooks/post-commit

Use tracedecay sync only as an explicit administrative refresh request when a diagnostic says the selected generation is stale; routine freshness remains a daemon-owned background journey.

Checking Your Setup with Doctor

The doctor command runs a read-only health check:

tracedecay doctor

It verifies:

Binary, location and version
Current project, registered project identity, final-store admission, exact worktree/ref/commit/generation, freshness, coverage, and typed authority state
Global registry, daemon-owned project/profile enrollment and availability
User config, ~/.tracedecay/config.toml and upload settings
Agent integrations. MCP server registration, hook installation, tool permissions, prompt rules
Network, the configured worldwide counter and GitHub releases API; each reports its own available or unavailable state, and a failed release lookup names its outcome (see Updating TraceDecay)

If any tool permissions are missing after an upgrade, Doctor reports the missing capability and the supported install/update operation. Doctor only reports state; refresh, retention, recreation, and host-config changes are separate authorized daemon operations.

Hosts that are not installed

A host TraceDecay tracks or finds leftover config for, but whose CLI is not on PATH, is reported as skipped with its reason and nothing else:

Factory Droid integration
  - droid: skipped, not installed (host CLI `droid` is unavailable for Factory Droid MCP registry lifecycle; install it or add it to PATH and retry)

Hosts TraceDecay configures through their documented config files (Kiro, Cline, Devin, Zed, and others) need no host CLI and no host sign-in.

A skipped host never counts as an issue, warning, or pending operator step, in doctor, install, update-plugin, reinstall, or update. Only defects in TraceDecay's own state, or in a host TraceDecay can reach, change the exit status.

One set of findings

Doctor asks the running daemon for its canonical findings (storage, runtime, code index, ingest coverage, memory owners, GitHub source, and the rest) and prints each one under Canonical Doctor findings with the statement and evidence the dashboard's Doctor view shows, for example:

✔ observability: durable ingest coverage records no refused source records (observability.ingest-coverage.converged)

When no daemon is listening for the profile, Doctor runs only its binary-local checks (binary, service unit, host integrations, external tools, release lookup) and reports the typed state in place of the findings:

… daemon_unavailable: no TraceDecay daemon is listening for this profile, ...

Start the daemon and re-run Doctor to read the findings.

Exit status and JSON

Exit	`doctor`	`install`, `update-plugin`, `reinstall`, `update`
`0`	no issue found; warnings and skipped hosts may be printed	every host completed, or was skipped as not applicable or `not installed`
`1`	an issue was found	a host's lifecycle ran and failed (or, for `update`, the upgrade failed)
`75`	no issue, but an operator step is pending: `daemon_unavailable`, a store the daemon serves reset-required, or a host's interactive activation (Kimi Code's `/plugins install`)	nothing failed, but a host waits on an interactive step (Kimi Code's `/plugins install`)

A project runtime that is still mounting (application.runtime.mounting) is reported as pending with a wait remedy; it does not change the exit status.

tracedecay doctor --json writes no human report and prints one JSON document on stdout with version, outcome (healthy, issue, or pending_operator_action), the issues / warnings / pending_actions counts, every check line in checks (level and message), and daemon_findings. daemon_findings.state is observed (carrying the /api/doctor/findings payload, projected by the same code the dashboard route uses, plus its domain_state, coverage, and freshness), daemon_unavailable when no daemon listens, mounting while the project runtime that owns the report is still mounting, or unread with a reason when a daemon answered without an observed report.

Finding Affected Tests

When you change source files, you often want to know which tests might be affected. The affected tool traces through the file dependency graph to find them. files is an array, so pass the whole arguments object with --args:

tracedecay tool affected --args '{"files":["src/main.rs","src/db/connection.rs"]}'

This performs a breadth-first search from the changed files through import/dependency edges to find test files that directly or transitively depend on those files.

Piping from git

This is especially useful in CI pipelines. --args - reads the arguments object from stdin, so build it from git diff:

git diff --name-only HEAD~1 \
  | jq -R -s -c '{files: (split("\n") | map(select(length > 0)))}' \
  | tracedecay tool affected --args -

There is no --stdin flag; the file list travels inside the arguments object.

Options

# limit traversal depth (default: 5)
tracedecay tool affected --args '{"files":["src/lib.rs"],"depth":3}'

# custom test file pattern
tracedecay tool affected --args '{"files":["src/lib.rs"],"filter":"*_test.rs"}'

# the tool result, with the typed payload under structuredContent
tracedecay tool affected --args '{"files":["src/lib.rs"]}' --json

MCP Tools for AI Agents

When running as an MCP server, tracedecay exposes typed operations that AI agents can call. Here's what they do, grouped by purpose.

Core exploration

Tool	What it does
`tracedecay_context`	Given a task description, returns relevant symbols, relationships, and code snippets. This is the go-to starting point for any coding task.
`tracedecay_grep`	Search indexed code content by literal string or regex, with each hit annotated by its enclosing symbol.
`tracedecay_search`	Find symbols by name. Supports filtering by kind (function, class, method, etc.).
`tracedecay_node`	Get full details for a specific symbol: source code, location, complexity metrics, and relationships.
`tracedecay_files`	List indexed files, optionally filtered by directory or glob pattern.
`tracedecay_status`	Index statistics: file counts, symbol counts, language distribution, and tokens saved.

Navigating relationships

Tool	What it does
`tracedecay_callers`	Find what calls a given function or method. Configurable traversal depth.
`tracedecay_callees`	Find what a function or method calls.
`tracedecay_impact`	Trace the full blast radius of changing a symbol, everything that could be affected.
`tracedecay_affected`	Find test files affected by source file changes.
`tracedecay_similar`	Find symbols with similar names (useful for naming patterns or related code).
`tracedecay_rename_preview`	Preview all references to a symbol before renaming it.

Code quality analysis

Tool	What it does
`tracedecay_dead_code`	Find unreachable symbols, functions with no callers.
`tracedecay_unmounted_files`	Find source files no build root reaches, indexed as healthy symbols, yet no compiler, bundler, or test runner ever loads them. Reports one section per ecosystem with its own verdict and blind spots.
`tracedecay_circular`	Detect circular file dependencies.
`tracedecay_recursion`	Detect recursive and mutually-recursive call cycles.
`tracedecay_complexity`	Rank functions by composite complexity score, including cyclomatic complexity from the AST.
`tracedecay_god_class`	Find classes with the most members, candidates for decomposition.
`tracedecay_hotspots`	Find the most connected symbols (highest call count). These are high-risk areas.
`tracedecay_doc_coverage`	Find public symbols missing documentation.

Health & quality signals

Tool	What it does
`tracedecay_health`	Composite quality signal (0–10000) from five structural dimensions (acyclicity, depth, equality, redundancy, modularity) with a low-weight penalty for `/// skip-test-coverage` overuse. The single number to track over time.
`tracedecay_gini`	Gini inequality coefficient for any metric (complexity, lines, fan-in, fan-out, members). Finds god files and uneven distributions.
`tracedecay_dependency_depth`	Longest file-level dependency chains, the critical paths where upstream changes ripple through the most layers.
`tracedecay_dsm`	Design Structure Matrix showing file dependencies as clusters, density stats, or an NxN grid. Reveals hidden coupling patterns.
`tracedecay_test_risk`	Risk-weighted test gaps combining complexity, coupling, git churn, and test coverage. Answers "where should the next test go?" Reports a static attribution lower bound (not line/branch coverage): each function is attributed via a direct test edge (`direct_unit`) or a depth-3 transitive path (`closure`), with the weaker `closure` method keeping a higher residual risk. See Reading the test_risk / test_map coverage signal for how to interpret the signal honestly on integration-heavy repos.

Test Coverage Conventions

`/// skip-test-coverage`

Mark functions that are genuinely untestable in unit tests (e.g. infrastructure-dependent, framework-invoked, or private helpers tested only transitively):

/// skip-test-coverage
pub async fn produce(&mut self, topic: &str, batch: Bytes) -> io::Result<i64> { ... }

Marked functions are excluded from tracedecay_test_risk attribution calculations, giving you an accurate picture of testable-code attribution (the skipped count appears in the summary). Note this is a static attribution signal, not executed coverage, see Reading the test_risk / test_map coverage signal.

Health penalty: The coverage_discipline dimension (visible in tracedecay_health and tracedecay_health_delta) penalises overuse. Each skipped function lowers the score proportionally, a few genuine exclusions have negligible impact, but marking 50%+ of your codebase as untestable will visibly reduce your quality signal. This encourages using the annotation for its intended purpose rather than as a way to game coverage numbers.

Structural analysis

Tool	What it does
`tracedecay_module_api`	Public API surface of a file or directory.
`tracedecay_coupling`	Rank files by coupling (fan-in or fan-out).
`tracedecay_inheritance_depth`	Find the deepest class inheritance hierarchies.
`tracedecay_type_hierarchy`	Recursive type hierarchy tree for traits, interfaces, and classes.
`tracedecay_distribution`	Node kind breakdown (classes, methods, fields) per file or directory.
`tracedecay_rank`	Rank nodes by relationship count (most-implemented interface, most-extended class, etc.).
`tracedecay_largest`	Rank nodes by size, largest classes, longest methods.

Git-aware tools

Tool	What it does
`tracedecay_diff_context`	Semantic context for changed files: modified symbols, dependencies, and affected tests.
`tracedecay_changelog`	Semantic diff between two git refs, which symbols were added, removed, or modified.
`tracedecay_commit_context`	Semantic summary of uncommitted changes, useful for drafting commit messages.
`tracedecay_pr_context`	Semantic diff between git refs for pull request descriptions.
`tracedecay_test_map`	Source-to-test mapping at the symbol level, with uncovered symbol detection. Finds test callers up to depth 3, so a listed test may be a direct caller or a transitive one, see Reading the test_risk / test_map coverage signal for the direct-vs-closure distinction.

Porting tools

Tool	What it does
`tracedecay_port_status`	Compare symbols between source/target directories to track cross-language porting progress.
`tracedecay_port_order`	Topological sort of symbols for porting, tells you what to port first based on dependencies.

Memory and fact recall

The holographic memory tools store durable facts linked to entities:

Tool	What it does
Exact `tracedecay_fact_store_*` tools	Store, search, update, remove, and reason over facts linked to entities such as symbols, files, branches, subsystems, people, or concepts.
`tracedecay_fact_feedback`	Record `helpful` or `unhelpful` feedback for a numeric `fact_id` so the fact's computed trust score changes over time.
`tracedecay_memory_status`	Read-only report of project/profile fact and entity counts, trust-score buckets, feedback counts, coverage, and missing-vector state. It never repairs or mutates storage.

Entity recall surfaces facts by named entity and includes why each fact was recalled: matching entities, reason text, related fact IDs, contradiction links, and the current trust score. Update old prompts and permissions to use the exact tracedecay_fact_store_* tools, tracedecay_fact_feedback, and tracedecay_memory_status.

Common exact fact-tool payloads (in add/search/probe order):

{"content": "Repository uses profile-wide host installs during active development.", "entities": ["install", "tracedecay"], "category": "project", "source": "user", "tags": ["preference"], "trust": 0.9}
{"query": "profile-wide host install preference", "min_trust": 0.5, "limit": 10}
{"entity": "tracedecay"}

Common tracedecay_fact_feedback payloads:

{"fact_id": 42, "action": "helpful", "source": "agent", "note": "Matched the current code path."}
{"fact_id": "42", "unhelpful": true, "source": "user", "note": "Superseded by a newer decision."}

For exact fields, inspect the live MCP descriptors; the generated schemas are the source of truth.

Discovery and analysis tools are read-only and safe to call in parallel. Session baseline, memory, and feedback mutations route through the daemon and return typed receipts; they never write host sidecars or open a project database directly. Edit tools modify source files.

Supported Languages

TraceDecay supports more than 50 languages, organized into three tiers. Each tier includes all the languages from the tier below it.

Lite (14 languages)

Always compiled. The smallest binary for the most popular languages.

Rust, Go, Java, Scala, TypeScript, JavaScript, Python, C, C++, Kotlin, C#, Swift, Svelte, Astro

Medium (Lite + 9 = 23 languages)

Adds scripting, config, and additional systems languages.

Dart, Pascal, PHP, Ruby, Bash, Protobuf, PowerShell, Nix, VB.NET

Full (Medium + 27+ languages)

Everything, including legacy and niche languages.

Lua, Zig, Objective-C, Perl, Batch/CMD, Fortran, COBOL, MS BASIC 2.0, GW-BASIC, QBasic, QuickBASIC 4.5

Mixing individual languages

Source builds can cherry-pick individual languages without taking a full tier:

cargo build -p tracedecay-cli --release --no-default-features --features lang-nix,lang-bash

What gets extracted

For each supported language, tracedecay extracts:

Function and method definitions (with signatures)
Class, struct, trait, interface, and enum definitions
Fields and properties
Import and export statements
Call relationships and type references
Docstrings and annotations
Complexity metrics (branches, loops, returns, max nesting, cyclomatic complexity)
Cross-file dependency edges

Privacy and Network

TraceDecay's core functionality is local-first. Indexing, search, graph queries, and the MCP server run through the local daemon and its embedded Grafeo/SQLite authority. Clients do not open database files directly. Default local and public-repository behavior needs no credential, but configured remote sources and authorities are distinct policy-bound effects.

Network effects are separate from local indexing and retrieval. They can be disabled, unavailable, or denied without turning those states into successful local results. The available effects are described below.

Worldwide token counter

TraceDecay tracks how many tokens it has saved locally. If you opt in, the daemon's token-savings status path uploads that aggregate count to the worldwide counter. Repository content, file names, and project names are not part of the counter payload. The counter service still receives ordinary transport metadata such as the source IP and may derive aggregate geography from it; submitting an aggregate count is not an anonymity guarantee.

This powers the "Worldwide" counter shown in tracedecay status only when the counter is enabled.

To opt in:

tracedecay enable-upload-counter

Disable it again at any time:

tracedecay disable-upload-counter

The setting belongs to your profile, not to a project: it applies everywhere and can be changed or read (tracedecay tool configuration_get --args '{"key":"user.upload_enabled.v1"}') from any directory.

Version check

TraceDecay checks GitHub release endpoints to show an upgrade notice. GitHub receives ordinary request metadata, including the connection source address and the TraceDecay user agent. A timeout or unavailable service means release metadata is unavailable, not that no update exists.

GitHub source and pull-request discovery

tracedecay init, and every later project open, binds the GitHub repository of the checkout's origin remote as the project's GitHub source (binding.tracedecay-daemon.github-origin in scope.source_bindings.v1). The binding follows origin when the remote changes. A GitHub binding you added yourself for another repository is left in place: a project has exactly one GitHub source.

Reads use the first credential available, in this order: GH_TOKEN, the gh auth token login, then the git credential helper's stored login for https://github.com. TraceDecay never stores the token. tracedecay status reports how the source is read, the pull-request discovery outcome for the checkout's exact head, and a remedy when there is one:

`github_source` state	Meaning
`bound`	A credential authorizes the reads.
`unauthenticated_public`	No credential was found, so the repository is read anonymously as a public repository. That allows 60 requests per hour. Discovery uses the REST issue search's `head:` qualifier, which also finds fork-headed pull requests.
`denied_no_credential`	No credential was found and GitHub refused the anonymous read: the repository is private or absent. Run `gh auth login`, or set `GH_TOKEN` to a token with read access, then reopen the project.
`absent`	No GitHub source was observed: the checkout has no GitHub `origin`, or its advisory owner has not mounted in this daemon yet.

Private GitHub review sources

An explicitly configured private GitHub review source can use an optional read-only credential from the operating-system keyring. Configuration stores a keyring locator rather than the secret itself. The daemon mounts the source only after verifying the exact read-only permission set; missing, ambiguous, write-capable, or unverifiable credentials fail closed.

Provider usage and pricing

TraceDecay records provider usage as immutable observations from exact native evidence. Each observation retains the provider/model identity, native scope and counter semantics, native field/kind, source range, and any native correlation identifiers. A read never infers missing identity or counters from a neighboring message, and cumulative-to-delta derivation remains deterministic and issue-marked.

tracedecay cost is a side-effect-free read over those observations. It uses one deterministic bundled all-provider pricing table, identified by its content digest. It does not make a request-triggered pricing fetch, write a home-directory pricing cache, or consult a pricing environment override. Missing native usage, unknown models, unavailable observations, or unavailable pricing remain typed unknown/unavailable results; TraceDecay never fills them with zero or a stale fallback estimate.

Configured remote authority

An explicitly configured, authenticated remote authority can perform policy-authorized remote retrieval, replication, backup, restore, or failover. Only authorized, sanitized, classified records can be exchanged, with exact source, retention, coverage, and receipt identity. The remote path fails closed with typed unavailable, denied, or stale-peer state; it does not turn a host, transport, or arbitrary endpoint into a TraceDecay storage authority.

See Security for the complete outbound-access, credential, and local-listener boundary.

Updating TraceDecay

When a new version is available, tracedecay tells you during status (or an explicit administrative refresh):

Update available: v3.3.3 -> v3.4.0
  Run: tracedecay upgrade

The upgrade command downloads the latest release from GitHub and replaces the binary in place:

tracedecay upgrade

Beta and stable are separate update channels, a beta build only sees beta releases and vice versa. Any attached MCP servers will continue running with the previous binary until you restart your agent.

Before anything is unpacked, upgrade checks the archive against the release's SHA256SUMS and then against its build-provenance attestation: it fetches the attestations GitHub holds for the archive's SHA-256 digest and verifies one of them against the Sigstore public-good trust root built into the binary (Fulcio certificate chain, Rekor transparency-log entry, DSSE signature, and an in-toto subject equal to the archive digest). The signing certificate must name this repository's release workflow for the channel (release-beta.yml or release.yml) run from master or from the release tag. On success it prints Build provenance verified: <workflow identity>. A missing attestation, one that fails verification, or one signed by any other identity refuses the upgrade; the checksum alone never suffices.

Release lookups send the same GitHub credential as project reads (GH_TOKEN, then gh auth token, then the git credential helper), which raises GitHub's quota from 60 to 5000 requests per hour. When a lookup fails, upgrade and doctor name the outcome and its remedy:

Outcome	Meaning
`rate_limited`	GitHub's API quota is exhausted; authenticate, or retry after the reported reset time.
`unauthorized`	GitHub refused the credential; refresh it with `gh auth login` or fix `GH_TOKEN`.
`network_unreachable`	No connection to GitHub (DNS, connect, TLS, or proxy).
`timed_out`	GitHub did not answer in time.
`malformed_response`	GitHub answered with a body that is not release metadata.
`unexpected_status`	GitHub answered with an HTTP status the lookup cannot interpret.
`no_asset_for_platform`	No release on your channel publishes your platform's asset yet; release CI may still be uploading.

After upgrading, re-run install if the host integration reports a missing capability, then inspect the daemon-owned status/coverage:

tracedecay install
tracedecay doctor
tracedecay status --json

If the status is reset_required, stop reads and writes for the affected authority and follow the daemon's typed remediation or reset instructions. Do not copy or edit database files, bypass the daemon, or reopen the authority until remediation completes or the daemon explicitly recreates the final store.

Scoped resets: `tracedecay wipe --stale --yes`

tracedecay doctor lists each store the daemon holds in its reset-required state as a pending operator action with the command that resets it. When that command is tracedecay wipe --stale --yes, the reset deletes exactly the stores the daemon reports and nothing else; the daemon recreates each one empty. Nothing is migrated or backed up. The stores it resets on their own:

Store	Files deleted	What is lost
profile authority	`~/.tracedecay/global.db` (`-wal`, `-shm`)	the project registry, usage accounting, and remote-deletion records
profile sessions	`~/.tracedecay/user-sessions.db` family	projectless session history and stored profile configuration
project sessions `<id>`	`~/.tracedecay/projects/<id>/sessions.db` family	that project's session history and stored configuration
profile / project hook admissions	the Hook V2 admission ledgers	pending hook admissions

The profile authority holds no session data, so a session-feature schema change (LCM, git correlation, workflows) resets only the session stores and never the registry.

A profile authority reset keeps every project store (code index, graph, sessions, memory) byte-identical. The registry it recreates is empty, so the reset prints one tracedecay init <path> command per project store whose root still exists; each project's store records its own root and identity, so init registers it again and keeps serving its existing code generation. A git checkout also registers itself again the first time a command runs in it. At startup the daemon inspects every project sessions store whose project root still exists, without opening the project, so a profile written by an earlier release lists each refused store at once and one wipe --stale --yes resets them all. A store this release's schema already admitted records that in its store_manifest.json and is not opened again until the schema changes. While the profile authority is reset-required, project commands refuse with this reset instead of serving: project routing resolves enrollment, linked worktrees, and remote-deletion records through the registry.

A store wipe --stale cannot reset on its own names tracedecay wipe --all --yes, which deletes every profile store, including project code indexes.

Configuration Files

TraceDecay stores data through one daemon-owned project/profile authority. Clients and hosts never open the underlying files directly.

User memory store

The profile-owned user-memory store stores durable user preferences and memory from chat sessions that are not attached to an initialized TraceDecay project. Use memory_scope=user with exact tracedecay_fact_store_* tools, tracedecay_fact_feedback, or tracedecay_memory_status. The CLI can access this scope outside any project. Hermes routes untethered chat and explicit user-preference writes here; projectless Codex and Cursor hooks recall from it.

Active project store

Projects enroll one daemon-owned project authority. Profile-backed storage keeps the final Grafeo/SQLite stores under the private profile root (~/.tracedecay/projects/<project-id>); a git repository additionally carries its identity in .git/tracedecay-project.json. Nothing is written into the visible working tree. Project facts, sessions, and lossless LCM are project-wide across branches and linked worktrees. Code graphs are indexed as immutable generations with exact repository, checkout, worktree, ref, commit/tree, snapshot, and generation provenance.

The user-level registry database records enrollment and routing metadata; it is not a fact authority. Retention, compaction, payload quarantine, and rebuilds are separate daemon operations with receipts. Hosts and clients never become a storage authority or open a database directly.

A leftover repo-local .tracedecay/enrollment.json from an older TraceDecay is not read; you can delete it. Do not copy or edit store files.

An incompatible persisted shape or incomplete privacy remediation returns ResetRequired/reset_required. Follow the daemon's remediation or explicitly recreate the final store; runtime never guesses, falls back, or exposes unverified content.

Cross-project reads

Most commands still default to the active project discovered from your current directory. For intentional cross-project reads, run commands from the target checkout or use the path selectors supported by each command:

tracedecay status /path/to/project --json
tracedecay memory status --path /path/to/project --json

tracedecay sessions search searches previously ingested sessions for the active project. By default it searches all ingested transcript providers; pass --provider <id> only when intentionally constraining the search. Use --project-id or --project-path to search a registered project other than the current directory.

Per-user: `~/.tracedecay/`

Created in your home directory. Contains:

config.toml, user preferences (upload opt-in/out, cached version info, pending upload count)
global.db, daemon-owned registry/usage metadata for enrolled projects; it is not a fact authority and clients never open it directly
projects/<project_id>/, daemon-owned project authority data when profile storage is enabled

The config.toml is plain TOML and fully transparent:

upload_enabled = false      # set to true to opt in to counter upload/read
pending_upload = 4823       # tokens waiting to be uploaded
last_upload_at = 1711375200 # last successful upload timestamp
last_worldwide_total = 1000000
last_worldwide_fetch_at = 1711375200

Mandatory structured sanitization of ingested transcripts

Agent transcripts can contain credentials or other sensitive values. TraceDecay applies one canonical, structured sanitizer to every ingest, replay, and derived-content path before content becomes durable or searchable. It parses JSON and other structured values before scanning, redacts values whose field meaning or credential evidence is sensitive, preserves valid document shape, and binds a SanitizationReceiptV1 to the source and sanitized content.

Sanitization is mandatory. It cannot be disabled, narrowed, or overridden by a profile setting, host configuration, or message metadata. LCM payloads are never retained verbatim: clean content is accepted, detected secrets are replaced and marked redacted/lossy, and malformed, oversized, unverifiable, or sanitizer-failing content is quarantined or rejected fail-closed. Externalized payloads are sanitized before storage and are represented in projections by a safe placeholder.

The daemon's LCM status reports scan, quarantine, derivative-rebuild, and reset-required phases. Reads remain locked while remediation is incomplete; the daemon sanitizes recoverable inline rows, quarantines content it cannot prove safe, rebuilds derivatives atomically, and requires explicit reset when the retained payload or privacy revision cannot be verified. Follow the typed status and reset instructions; never copy or edit store files or hand-edit sanitization metadata.

Troubleshooting

"tracedecay not initialized"

TraceDecay could not find an initialized project store for your current directory. Run:

tracedecay init

"code_index_scheduler_unavailable" from `init`

Error: project route error (code_index_scheduler_unavailable): project initialization requires the daemon-owned code-index scheduler; start the daemon and retry

No daemon is accepting connections for this profile, so init refused before writing anything. Start one and retry:

tracedecay daemon install-service   # or: tracedecay daemon start
tracedecay daemon status
tracedecay init

MCP server not connecting

Your AI agent doesn't see tracedecay tools.

Run tracedecay doctor to check the integration
Verify tracedecay is on your PATH: which tracedecay
Re-run tracedecay install and restart your agent completely

The CLI fallback is another client of the same daemon, not a guarantee that the daemon is available. If Doctor reports a stopped, missing, or unavailable daemon, preserve that state unless you explicitly intend to start it. Do not loop on MCP/CLI retries or treat a held daemon as permission to run a lifecycle command.

Missing symbols in search

Some symbols aren't showing up.

Check tracedecay status --json for the selected generation and typed warming/refresh-required state. Request an explicit administrative refresh only when the daemon reports it is needed.
Check that the language is supported (see the tiers above)
Verify the file is in Git's view of the worktree (not ignored by .gitignore) and not matched by index.exclude.v1 (see What gets indexed)

Indexing is slow on first run

The initial generation of a large project can take a few seconds. This is normal. Use daemon status/coverage to see warming progress and backlog state.

Subsequent daemon reconciliations are incremental and much faster
Routine updates are daemon-owned; do not build a client-side refresh loop into your day-to-day workflow.
Post-commit and daemon hook notifications are bounded and fail open so a slow or unavailable daemon does not hold up agent work for long.

Stale install warning

If you see a warning about your install being stale after an upgrade, run:

tracedecay install

This updates tool permissions, hooks, prompt rules, and plugin bundles where applicable to match the new version.

Getting help

If you run into something not covered here, check the GitHub repository or open an issue.

FilesExpand file tree

USER-GUIDE.md

Latest commit

History