trustcode

Verifiable code intelligence for AI agents — every answer comes with the evidence that proves it.

trustcode indexes a repository into a compact, evidence-backed knowledge graph of symbols, relationships, execution flows, and routes, then serves it to AI coding agents through a CLI and an MCP server. When an agent asks "how does login create a session?" or "what breaks if I change this function?", trustcode answers with the source evidence and a confidence score behind every claim — so the agent can act without re-reading files and without trusting guesses.

It is local-first (no hosted service, no network calls by default) and ships as a single native Rust binary.

Built with AI coding agents

trustcode is developed primarily by AI coding agents — fitting, since it's a code-intelligence tool for agents, dogfooded by being built with them.

Contribution norm: the vast majority of code changes are expected to be made by AI coding agents, with humans steering. Most source in this repository was authored by an agent and gated through CI before merging.

Humans drive the project from a level up:

• Open issues — report bugs, request features, propose direction.
• Review & discuss — weigh in on pull requests and architecture.
• Direct an agent — hand a task to a coding agent and review the result.

See AGENTS.md and CONTRIBUTING.md for the workflow.

The Trust Contract

trustcode never states a relationship as fact without attaching the evidence that proves it and a confidence score. Exact matches are marked exact. Inferences are marked as inferences. The agent always knows what is proven and what is guessed.

Every non-trivial relationship stored carries a provenance, a confidence (0–1), and an evidence record (the exact source span that justifies it). Weak guesses are recorded with low confidence and kept out of default answers.

Install

From npm (single static binary, no toolchain)

Install globally so the trustcode command is on your PATH (recommended — the rest of this README uses the bare trustcode command):

npm install -g @startrust/trustcode
trustcode index

Or run it without installing, via npx — but then prefix every command with npx @startrust/trustcode (e.g. npx @startrust/trustcode status):

npx @startrust/trustcode index

Either way, the launcher selects and runs the prebuilt binary for your platform (win32/linux/darwin × x64/arm64).

From source

cargo build --release
# binary at target/release/trustcode

Requires a Rust toolchain. SQLite is compiled in (bundled), so no external database is needed.

Quick start

These examples use the bare trustcode command (global install). If you're using npx, prefix each one with npx @startrust/trustcode.

trustcode index                       # build .trustcode/trustcode.db for the current repo
trustcode status                      # files / symbols / relationships / flows
trustcode find createSession          # locate symbols by name
trustcode show SessionStore.create    # signature + source slice
trustcode trace loginHandler createSession   # evidenced call path, one record per hop
trustcode explain "how does login create a session"
trustcode impact createSession        # what depends on it, risk level, affected flows/tests
trustcode routes                      # API routes -> handlers -> consumers
trustcode sync                        # incremental re-index (re-parses only changed files)
trustcode init                        # install git hooks that auto-sync after commit/merge/checkout

Keeping the index fresh

Three ways the graph stays current — mirroring how the index should never go stale:

• While serving: trustcode serve --mcp runs a catch-up sync on start, then watches the source tree and incrementally re-syncs (debounced) on every change — no manual step.
• Git hooks: trustcode init installs post-commit / post-merge (covers git pull) / post-checkout hooks that run trustcode sync in the background.
• Manual: trustcode sync any time.

sync is incremental — unchanged files are reloaded from stored per-file artifacts and only changed files are re-parsed, yet the result is always identical to a fresh index.

Example: trace

loginHandler  [function]  (src/auth.ts:3)
  ↓ calls  [conf 0.90]  line 4  createSession(validateCredentials(req))
createSession  [function]  (src/session.ts:1)

Example: explain

explain returns a single, self-contained Answer in eight sections — enough to act on without opening a file. For trustcode explain "how does loginHandler create a session":

## summary
loginHandler  [function]  src/auth.ts:2-4  (exported)
Calls 2 symbol(s); called by 0 symbol(s).

## matched_flows
loginHandler -> persist  (3 steps, conf 0.90)

## primary_trace
loginHandler  [function]  (src/auth.ts:2)
  ↓ calls  [conf 0.90]  createSession(validateCredentials(req))
createSession  [function]  (src/session.ts:1)
  ↓ calls  [conf 0.90]  persist(userId)
persist  [function]  (src/session.ts:2)

## source_slices
   2 | export function loginHandler(req) {
   3 |   return createSession(validateCredentials(req));
   4 | }

## evidence
[import-resolved] conf 0.90  createSession(validateCredentials(req))
[same-file-call]  conf 0.90  persist(userId)

## related_tests        (none found)
## uncertain_steps      (none)
## suggested_next_symbols
createSession  [function]
validateCredentials  [function]

Every hop names the rule and confidence behind it — that's the Trust Contract in practice.

MCP server

trustcode speaks the Model Context Protocol over stdio, exposing seven tools: trustcode_status, trustcode_files, trustcode_find, trustcode_show, trustcode_trace, trustcode_explain, trustcode_impact.

trustcode serve --mcp

Connecting a client

One-step project setup (Claude Code + Codex):

trustcode install      # then run `trustcode index` once

install writes project-local, committable config so the whole team gets trustcode after a clone:

• Claude Code — .mcp.json (MCP server), and .claude/settings.json pre-approving the mcp__trustcode__* tools plus hooks that show index status on session start and re-sync after edits.
• Codex — .codex/config.toml (MCP server).
• AGENTS.md — a short guidance block (read by both tools) telling the agent to prefer the trustcode_* tools and to run trustcode index if the project isn't indexed yet.

The commands use npx @startrust/trustcode@latest, so teammates don't need a global install and always launch the newest release; pass --global-bin to use a globally-installed trustcode instead. trustcode uninstall removes it all cleanly. (The local index under .trustcode/ is git-ignored, so each clone runs trustcode index once.)

Manual / other clients — register the server yourself:

{
  "mcpServers": {
    "trustcode": { "command": "npx", "args": ["-y", "@startrust/trustcode@latest", "serve", "--mcp"] }
  }
}

Or claude mcp add trustcode -- npx -y @startrust/trustcode@latest serve --mcp.

stdout carries only protocol traffic; logs go to stderr. While serving, the index incrementally syncs on file changes (see Keeping the index fresh); an unindexed project is left untouched with a hint to run trustcode index.

Staying up to date

trustcode ships often. Config written by trustcode install pins @latest, so the MCP server and hooks always launch the newest release. If you run the binary directly, it checks the npm registry at most once a day — only in an interactive terminal — and prints a one-line hint when a newer version exists (npm i -g @startrust/trustcode@latest to update). Set TRUSTCODE_NO_UPDATE_CHECK=1 to turn the check off; it never runs in pipes, hooks, or CI.

What it understands today

Languages

Native tree-sitter parsing, driven by per-language .scm query files.

Language	Extensions	Export rule	Status
TypeScript / TSX	.ts .tsx .mts .cts	export	✅
JavaScript / JSX	.js .jsx .mjs .cjs	export	✅
Rust	.rs	pub	✅
Go	.go	capitalization	✅
Python	.py .pyi	non-underscore name	✅

Call resolution is same-file + import-resolved + unique-global; language-specific module/import resolution is partial. Exact, type-aware resolution via a language server is the planned precision layer.

Graph

• Symbols: functions, classes, interfaces, methods (Class.method), arrow consts, React components
• Relationships: imports, calls (same-file / import-resolved / weak global), each with evidence + confidence
• Flows: execution paths derived from the call graph
• Data-flow (symbol-level): flows_to edges from nested calls (outer(inner()) → inner flows to outer), surfaced by show as "flows into" / "fed by". Variable-level def-use is a planned deeper layer
• Frameworks: Express routes, Next.js route.ts handlers, fetch/axios consumers (route_to_handler and fetches_route edges)
• Impact: upstream blast radius with LOW/MEDIUM/HIGH/CRITICAL risk and affected flows/tests

How it stores things

A project-local .trustcode/trustcode.db (SQLite + FTS5), git-ignored. The schema keeps nodes (symbols) and edges (relationships); every edge carries provenance, confidence, and an evidence JSON record from the first migration.

Architecture

A Cargo workspace of focused crates. Data flows one way — scan → extract → resolve → flow → db — and both front-ends query through the shared trustcode-db::query layer, so the CLI and MCP server always return identical Answers.

crate	responsibility
trustcode-core	domain types, stable IDs, path normalization (no I/O deps)
trustcode-scan	git-aware file discovery, ignore rules, content hashing, change detection
trustcode-extract	tree-sitter symbol/import/call/route/data-flow extraction (.scm queries)
trustcode-resolve	call / route / data-flow resolution into evidenced edges
trustcode-flow	execution-flow detection
trustcode-db	SQLite schema, migrations, and the shared query layer (Answers)
trustcode-mcp	MCP stdio server (rmcp)
trustcode-cli	the trustcode binary

Development

cargo test                                   # unit + integration + blind-answer recall eval
cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
bash benchmarks/run.sh                       # dogfood-index real repos and report numbers

CI runs fmt + clippy (deny warnings) and the test suite across Linux/macOS/Windows; all must be green to merge. See AGENTS.md for the full engineering playbook.

Status

Working today: index → symbols → evidenced call graph → flows → trace / explain / impact / routes over both CLI and MCP. 7 languages (TypeScript, JavaScript, TSX, JSX, Rust, Go, Python), symbol-level data-flow, incremental sync, a file watcher and git hooks, npm packaging, and cross-platform CI.

Planned next: a TypeScript language-server precision layer (exact, type-aware resolution at confidence 1.0) and variable-level data-flow.

License

MIT