Skip to content

Getting Started

This guide walks from zero to a working CodeRecon + AI tool setup in about 5 minutes.

Prerequisites

  • Python 3.12+
  • A Git repository
  • One of: VS Code, Claude Code, Cursor, or OpenCode

Containerized environments

CodeRecon runs as a local Python process on the same machine as your source code. If your project's runtime, dependencies, or configuration live exclusively inside a Docker container or dev container, CodeRecon cannot inspect them. Dependency resolution, environment detection, and framework discovery may be degraded or unavailable when the host filesystem does not reflect the actual project environment.

Installation

pip install coderecon

pipx install coderecon

uv tool install coderecon

Verify the install:

recon --version

Step 1 — Start the Daemon

CodeRecon runs as a single global background daemon. Start it once; it manages all your registered repos.

recon up

You'll see the CodeRecon banner and the daemon URL. Leave this terminal open, or run it as a background process.

Keep it running

Run recon up once per session. The daemon persists across recon register / recon unregister calls — no restart needed.

Step 2 — Register Your Repo

From inside your repository:

cd /path/to/your/repo
recon register

This does three things:

  1. Creates .recon/ with config and index storage
  2. Builds the initial index (tree-sitter parse + Tantivy full-text)
  3. Writes MCP config for your detected AI tool(s)

What gets written

recon register auto-detects installed tools and writes the right config file for each:

Detected tool File written
VS Code / Copilot .vscode/mcp.json
Claude Code .mcp.json
Cursor .cursor/mcp.json
OpenCode ~/.config/opencode/config.json

It also injects a CodeRecon instruction snippet into the tool's agent instruction file (.github/copilot-instructions.md, CLAUDE.md, etc.) so your agent knows the MCP tool prefix and required workflow.

Targeting specific tools

Use --mcp-target to be explicit: 

recon register --mcp-target vscode --mcp-target claude
recon register --mcp-target all
See MCP Setup for the full flag reference.

Step 3 — Verify the MCP Connection

VS Code / GitHub Copilot

  1. Open VS Code in the registered repo
  2. Open the Copilot Chat panel
  3. Switch to Agent mode (the @ dropdown)
  4. Look for coderecon in the MCP servers list

Claude Code

# From inside the repo
claude
> /mcp   # should list coderecon

Cursor

  1. Open Cursor settings → MCP
  2. Verify coderecon appears and is enabled

OpenCode

opencode
# MCP servers are loaded automatically from ~/.config/opencode/config.json

Step 4 — Run Your First Recon

Once connected, ask your agent to run a recon call:

recon(task="understand the authentication module", seeds=["AuthService", "login"], read_only=true)

The response contains:

  • Ranked results — top half with full code snippets, bottom half with signature + docstring only
  • Gate — quality signal (OK, UNSAT, BROAD, AMBIG)
  • Metrics — retrieval diagnostics
  • Hint — actionable follow-up guidance

Typical Agent Workflow

Read-only research

recon(task="how does caching work?", read_only=true)
→ [agent reads files based on results]
→ checkpoint(changed_files=[])              # no-op, reset session state

Edit a file

recon(task="add retry logic to fetch()", read_only=false)
→ [agent reads and edits files]
→ checkpoint(changed_files=["src/client.py"], commit_message="feat: add retry")

Rename a symbol

recon(task="rename UserProfile → Profile", read_only=false)
→ refactor_rename(symbol="UserProfile", new_name="Profile", justification="...")
→ refactor_commit(refactor_id="...", inspect_path="src/models.py")  # review ambiguous
→ refactor_commit(refactor_id="...")                                  # apply
→ checkpoint(changed_files=["src/models.py", ...], commit_message="refactor: rename")

Explore an unfamiliar repo

recon_scout()                               # repo-wide orientation
recon_scout(scope="src/auth")               # zoom into auth module
recon(task="...", read_only=true)            # targeted retrieval

Registering More Repos

Each repo gets its own daemon slot. Register as many as you like:

cd ~/projects/frontend && recon register
cd ~/projects/backend  && recon register
cd ~/projects/infra    && recon register

Check what's registered:

recon catalog

Updating the Index

The index stays current automatically as you edit files (via the file watcher). To force a full rebuild:

recon register --reindex