Coderecon

CodeRecon

Local repository control plane for AI coding agents

---

CodeRecon is a background daemon that sits between AI coding agents and your repository. It builds a structural index of your codebase and exposes deterministic, structured tools via the Model Context Protocol (MCP).

Agents get three things they can't do well on their own: fast cross-file context retrieval, safe structural refactors (rename/move with certainty ratings), and a lint → test → commit pipeline that uses the import graph to pick the right tests.

What it does

Retrieves context in one call. recon(task="...") returns ranked code spans with snippets from across the repo — no grep loops. A quality gate (OK / UNSAT / BROAD / AMBIG) tells the agent whether retrieval succeeded before it starts editing.

Refactors deterministically. refactor_rename and refactor_move compute all edits up front, assign each hunk a certainty level (high/medium/low), and let the agent inspect ambiguous matches before committing. Cross-file, atomic, no search-and-replace guessing.

Closes the loop. checkpoint(changed_files=[...]) runs auto-detected linters with autofix, selects affected tests via the import graph (direct importers first, transitive only if those pass), and commits — one call instead of a manual lint → pytest → git add → git commit chain.

Quick start

pip install coderecon-ai

recon up                    # start the daemon
cd /path/to/your-repo
recon register              # index the repo + configure your AI tool

recon register auto-detects your editor (VS Code, Claude Code, Cursor, OpenCode), writes the MCP config, and injects agent instructions. Your agent immediately gets access to CodeRecon tools.

What agents get

15 MCP tools organized around a typical task flow:

recon_scout(scope="src/auth")          → orient: structure, cycles, communities, health
recon(task="...", seeds=["AuthSvc"])    → retrieve: ranked code spans with snippets
recon_impact(target="AuthService")     → analyze: every reference, with certainty
refactor_rename(symbol="AuthService",
    new_name="AuthNService", ...)      → refactor: preview with per-hunk certainty
refactor_commit(refactor_id="...")     → apply: atomic cross-file rename
checkpoint(changed_files=[...],
    commit_message="...")              → verify: lint → test → commit → push

Plus semantic_diff, graph_cycles, graph_communities, blast_radius, covering_tests, recon_line_coverage, and describe for self-documentation.

How it works

The daemon maintains a four-tier index per repo:

• Tier 0 — Tantivy lexical index (fast text search)
• Tier 1 — Tree-sitter structural facts (definitions, references, imports, scopes)
• Tier 2 — Type-level facts (annotations, member access, interface implementations)
• Tier 3 — Behavioral facts (test coverage, call edges, lint status, endpoints)

A file watcher keeps the index fresh as you edit. recon queries run through a retrieval → gate → rank → cutoff pipeline backed by SPLADE sparse retrieval and LightGBM LambdaMART scoring.

Multi-repo, multi-tool

One daemon manages all your repos. Register as many as you like:

recon register ~/projects/frontend
recon register ~/projects/backend
recon catalog                        # see everything

Supports VS Code / Copilot, Claude Code, Cursor, and OpenCode. Git worktrees are first-class.

Docs

dfinson.github.io/coderecon — full documentation including:

• Getting Started — zero to working setup
• MCP Tools Reference — all 15 tools with parameters
• Architecture — index tiers, ranking, daemon design
• CLI Reference — operator commands
• Configuration — config schema, env vars, precedence
• MCP Setup — manual config and troubleshooting
• Testing — 27 runner packs across 21 languages

Contributing

git clone https://github.com/dfinson/coderecon.git
cd coderecon
uv sync --all-extras
recon up && recon register

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dfinson
• Source: dfinson/coderecon
• License: MIT
• Homepage: https://dfinson.github.io/coderecon/

Install and usage instructions live in the source repository linked above.