CodeRecon¶

Code intelligence for AI agents

Your agent wastes most of its time reading, not thinking. Fix that.

AI coding agents burn most of their token budget on exploratory grep loops, file reads, and retries just to understand what they're looking at. Renames take minutes of find-and-replace. Test runs are blind. CodeRecon is a daemon that indexes your repo and gives agents structured tools to retrieve context, refactor safely, and verify changes — through MCP.

Quick Start MCP Tools Architecture

Works with VS Code / Copilot, Claude Code, Cursor, and OpenCode · Open source, MIT license

Get Running in 30 Seconds¶

pip install coderecon

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

recon register detects your editor, writes the MCP config, and injects agent instructions. Your agent immediately has access to all 15 tools. No manual wiring.

Before / After Agent Workflow

What It Solves¶

Context retrieval without the grep spiral¶

Without CodeRecon, agents grep → open file → read → grep again → open another file, looping until they've built enough context. With CodeRecon, one recon(task="...") call returns ranked code spans from across the repo — full snippets for the top results, signatures for the rest. A quality gate tells the agent whether it found what it needs before it starts editing.

Refactors that don't break things¶

Without CodeRecon, agents do string find-and-replace across files and hope for the best. With CodeRecon, refactor_rename and refactor_move use the structural index to compute all edits up front, assign each hunk a certainty level (high / medium / low), and let the agent review ambiguous matches before applying. Cross-file, atomic, import-aware.

Verify before you commit¶

Without CodeRecon, agents run the full test suite (or skip tests entirely), lint manually, and cobble together git commands. With CodeRecon, the daemon runs affected tests and linters automatically in the background as you edit. checkpoint reads the cached results, and if everything passes, commits — one call. If no cached run is available, it falls back to live test discovery via the import graph.

How It Works¶

A background daemon indexes each registered repo and keeps the index fresh via file watching.

Structural Index¶

Tree-sitter parses every source file into definitions, references, imports, scopes, and type annotations across four tiers. A Tantivy full-text index provides fast lexical search. Coverage data, call edges, and lint status round out the behavioral tier.

Learned Ranking¶

Retrieval results are scored by a LightGBM pipeline with SPLADE sparse retrieval and cross-encoder reranking. The ranker was trained on real agent retrieval tasks, not synthetic benchmarks.

Graph Analysis¶

Dependency cycle detection (Tarjan), module community detection (Louvain), and PageRank-ranked symbols. recon_scout combines all three for one-call repo orientation.

Test Impact¶

blast_radius traces which tests cover changed definitions. covering_tests maps functions to their tests. recon_line_coverage gives per-line hit counts. 12 coverage parsers across Python, JS, Go, Rust, Java, .NET, Ruby, and PHP.

Multi-Repo Daemon¶

One process manages all your repos. Register as many as you like — each gets its own index, kept fresh by a file watcher. Git worktrees are first-class. WSL cross-filesystem detection is automatic.

27 Runner Packs¶

Test discovery and execution across 21 languages: pytest, jest, vitest, go test, cargo nextest, maven, gradle, dotnet, rspec, phpunit, and more. All auto-detected from project config.

When to Use It¶

Your agent spends more time reading than editing. CodeRecon front-loads ranked context so the agent can start working immediately instead of exploring.
You need cross-file renames that don't break imports. The structural index resolves references precisely — no regex guessing.
You want lint + test + commit as one atomic operation. Import-graph-aware test selection means only affected tests run, and the commit only happens if everything passes.
You manage multiple repos. One daemon, one port, every repo indexed and queryable.