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-ai

pipx install coderecon-ai

uv tool install coderecon-ai

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 correct MCP config file for each (VS Code, Claude Code, Cursor, OpenCode). It also injects a CodeRecon instruction snippet into each tool's agent instruction file. See MCP Setup for the full list of config file locations and formats.

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

See Tools — Typical Agent Workflow for the full reference. The short version:

Task Flow
Research recon(read_only=true) → read files → checkpoint(changed_files=[])
Edit recon(read_only=false) → edit files → checkpoint(commit_message="...")
Rename recon → refactor_rename → refactor_commit → checkpoint
Explore recon_scout() → recon_scout(scope="...") → recon(task="...")

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