coderecon

<p align="center"> <img src="docs/images/logo.png" alt="CodeRecon Logo" width="200"> </p> <h1 align="center">CodeRecon</h1> <p align="center"> <strong>Local repository control plane for AI coding agents</strong> </p> <p align="center"> <img src="https://img.shields.io/badge/status-alpha-yellow" alt="Status: Alpha"> <img src="https://img.shields.io/badge/python-≥3.12-blue" alt="Python ≥3.12"> <a href="https://codecov.io/gh/dfinson/coderecon"><img src="https://codecov.io/gh/dfinson/coderecon/branch/main/graph/badge.svg" alt="Coverage"></a> <img src="https://img.shields.io/github/license/dfinson/coderecon" alt="License"> </p> --- 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](https://modelcontextprotocol.io/) (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 ```bash 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: ```bash 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](https://dfinson.github.io/coderecon/)** — full documentation including: - [Getting Started](https://dfinson.github.io/coderecon/getting-started/) — zero to working setup - [MCP Tools Reference](https://dfinson.github.io/coderecon/tools/) — all 15 tools with parameters - [Architecture](https://dfinson.github.io/coderecon/architecture/) — index tiers, ranking, daemon design - [CLI Reference](https://dfinson.github.io/coderecon/cli/) — operator commands - [Configuration](https://dfinson.github.io/coderecon/configuration/) — config schema, env vars, precedence - [MCP Setup](https://dfinson.github.io/coderecon/mcp-setup/) — manual config and troubleshooting - [Testing](https://dfinson.github.io/coderecon/testing/) — 27 runner packs across 21 languages ## Contributing ```bash git clone https://github.com/dfinson/coderecon.git cd coderecon uv sync --all-extras recon up && recon register ``` ## License [MIT](LICENSE)