Recon

Why Recon?

AI coding agents are blind to architecture. They grep, they guess, they break things.

Recon fixes this by indexing your codebase into a knowledge graph — functions, classes, call chains, imports, communities — and exposing it through 14 MCP tools, 3 prompts, and 5 resources that any AI agent can query.

💡 One command, full awareness. Your agent gets dependency mapping, blast radius analysis, safe renames, execution flow tracing, Cypher queries, and hybrid semantic search — without reading every file.

Quick Start

# Index your project (zero config)
cd /path/to/your/project
npx recon-mcp index

# Start MCP server for AI agents
npx recon-mcp serve

# Or start HTTP REST API + interactive dashboard
npx recon-mcp serve --http
# → http://localhost:3100

Global install (optional):

npm install -g recon-mcp
recon index && recon serve

Requires Node.js ≥ 20. Tree-sitter grammars are bundled as npm dependencies.

Features

🔍 Code Intelligence

• 13 languages via tree-sitter + dedicated analyzers

• Multi-repo indexing and cross-repo queries

• Community detection — automatic module clustering (label propagation)

• Blast radius — know what breaks before you touch it

• Graph-aware rename — safe multi-file renames

• Execution flow tracing — BFS from entry points through call chains

• Cross-language tracing — follow API calls across Go ↔ TypeScript

• PR Review — graph-aware blast radius, risk assessment, affected flows

⚡ Search & Query

• BM25 search — camelCase/snake_case tokenization with relevance ranking

• Hybrid semantic search — vector embeddings (all-MiniLM-L6-v2) + RRF fusion

• Cypher-like queries — MATCH/WHERE/RETURN structural queries

• MCP Resources — recon:// URIs for packages, symbols, files, processes, stats

• MCP Prompts — guided workflows for impact analysis, architecture docs, onboarding

• Framework detection — automatic entry point multipliers for 20+ frameworks

• Live re-index — file watcher with surgical graph updates (~50ms per file)

• Graph auto-save — persists graph to disk every 5 updates or 30s, survives restarts

• Graph export — Mermaid flowchart or Graphviz DOT, filterable by package/symbol/type

Supported Languages

Kotlin and Swift require optional grammars: npm install tree-sitter-kotlin tree-sitter-swift Go grammar (tree-sitter-go) is bundled by default.

Enhanced Search (Optional)

By default, Recon uses BM25 keyword search. For hybrid semantic search (find conceptually similar code, not just exact name matches), install one optional package:

npm install @huggingface/transformers

Recon auto-detects it and enables hybrid BM25 + vector search with all-MiniLM-L6-v2 embeddings. No extra config or flags needed — just install and re-index.

Graph Export

Export the knowledge graph as Mermaid (paste in GitHub PRs/docs) or Graphviz DOT (render to SVG):

# Mermaid flowchart for a package
recon export --package mcp --limit 20

# DOT ego graph around a symbol
recon export --format dot --symbol handleQuery --depth 2

# Filter by node types and edge types
recon export --type Function,Interface --edges CALLS

# Pipe DOT to SVG
recon export --format dot | dot -Tsvg > architecture.svg

Also available as MCP tool recon_export — agents can generate diagrams directly in conversation.

PR Review

Graph-aware code review — know what breaks before you merge:

# Review all uncommitted changes
recon review

# Review current branch vs main
recon review --scope branch --base main

# Review only staged changes
recon review --scope staged

Output includes: per-file risk (🔴🟡🟢), blast radius, affected execution flows, architecture diagram, and review priorities. Also available as MCP tool recon_pr_review.

How It Works

You add MCP config → Agent starts Recon automatically → Done.

When your AI agent starts:

1. Agent reads MCP config → runs npx recon-mcp serve

2. npx downloads Recon from npm (cached after first run)

3. Recon auto-indexes the project (cwd) → creates .recon/ folder

4. File watcher starts → monitors source files for changes

5. MCP server opens on stdio (stdin/stdout) — no network, no port

6. Agent sees 14 tools + 3 prompts + 5 resources

7. Agent receives built-in instructions → knows when to use each tool

8. You edit code → graph updates surgically in ~50ms → auto-saved to disk → agent always has fresh data

Zero config. Zero commands. Fully automatic.

MCP Integration

Single Project

Add to your AI agent's MCP config:

Claude Code (.claude/mcp.json)

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

cwd tells Recon which project to index. It scans code from this directory and creates .recon/ there.

Multiple Projects

Index and watch multiple projects from a single Recon server using --projects:

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve", "--projects", "/path/to/frontend"],
      "cwd": "/path/to/backend"
    }
  }
}

This creates a merged graph — both projects are indexed, watched, and querable from a single MCP server. Use recon_list_repos to see all repos, and the repo parameter on any tool to filter.

Alternatively, run separate servers per project:

{
  "mcpServers": {
    "recon-backend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/backend"
    },
    "recon-frontend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/frontend"
    }
  }
}

### Multi-Repo (Merged Graph)

For cross-project queries (e.g., tracing API calls from frontend to backend), use multi-repo mode:

```bash
# Index each project with a name
cd /path/to/backend  && npx recon-mcp index --repo backend
cd /path/to/frontend && npx recon-mcp index --repo frontend

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/backend"
    }
  }
}

Then filter by repo in queries: recon_query({query: "Auth", repo: "backend"}). Use recon_list_repos to see all indexed repos.

Auto-Indexing

recon serve handles indexing automatically:

Built-in Instructions: Recon automatically injects MCP server instructions into the agent's system prompt. The agent will proactively use recon_impact before editing, recon_context for exploration, and recon_rename for safe renames — no manual prompting needed.

CLI Commands

recon index                        # Index codebase (incremental)
recon index --force                # Force full re-index
recon index --repo my-backend      # Index as named repo (multi-repo)
recon index --embeddings           # Include vector embeddings for semantic search

recon serve                        # Start MCP server on stdio (auto-indexes + live watcher)
recon serve --projects ../frontend # Watch additional project directories
recon serve --http                 # Start HTTP REST API + dashboard on :3100
recon serve --http --port 8080     # Custom port
recon serve --no-index             # Skip auto-indexing and file watcher
recon serve --no-watch             # Auto-index but disable file watcher
recon serve --repo my-backend      # Serve specific repo only

recon export                       # Export graph as Mermaid flowchart
recon export --format dot          # Export as Graphviz DOT
recon export --symbol handleQuery  # Ego graph around a symbol

recon review                       # PR review — blast radius + risk
recon review --scope branch        # Review branch diff vs main
recon review --scope staged        # Review staged changes only

recon status                       # Show index stats
recon status --repo my-backend     # Status for specific repo
recon clean                        # Delete index
recon init                         # Create .recon.json config file

Auto-index: serve checks if the index is up-to-date with the current Git commit. If stale, it re-indexes automatically before starting. Use --no-index to skip.

Configuration

Create a .recon.json at your project root to persist settings:

recon init  # Creates .recon.json with defaults

// .recon.json
{
  "projects": ["../frontend"],   // Additional dirs to index + watch
  "embeddings": false,           // Enable vector embeddings
  "watch": true,                 // Enable live file watcher
  "watchDebounce": 1500,         // Debounce interval (ms)
  "ignore": ["generated/"]       // Extra paths to ignore
}

Priority: CLI flags always override .recon.json, which overrides defaults.

With a config file, your MCP setup stays minimal:

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/project"
    }
  }
}

No more long args arrays — all config lives in .recon.json.

Tool Reference

All 14 tools accept an optional repo parameter for multi-repo filtering.

recon_packages

List all packages/modules with dependency relationships.

recon_packages(language?: "go" | "typescript" | "all")

recon_query

BM25 ranked search with automatic camelCase/snake_case tokenization. Exact names rank highest. Supports optional hybrid BM25 + vector search with Reciprocal Rank Fusion.

recon_query(query: string, type?: string, language?: string, semantic?: boolean, limit?: number)

recon_context

360° view of a symbol — callers, callees, imports, methods, implementations, community membership.

recon_context(name: string, file?: string, includeSource?: boolean)

recon_impact

Blast radius analysis — what breaks if you change a symbol. Includes affected communities and confidence tiers.

recon_impact(target: string, direction: "upstream" | "downstream", maxDepth?: number)

Risk levels: LOW (0–2 d1) · MEDIUM (3–9) · HIGH (10–19) · CRITICAL (20+ or cross-app)

recon_detect_changes

Map git diff to affected symbols and trace blast radius.

recon_detect_changes(scope?: "unstaged" | "staged" | "all" | "branch", base?: string)

recon_api_map

Cross-language API route map — endpoint → Go handler → TypeScript consumers.

recon_api_map(method?: string, pattern?: string, handler?: string)

recon_rename

Safe multi-file rename using the knowledge graph. Each edit is tagged with confidence: graph (high, safe to accept) or text_search (review carefully).

recon_rename(symbol_name: string, new_name: string, dry_run?: boolean)

recon_query_graph

Cypher-like structural queries against the knowledge graph.

MATCH (a)-[:CALLS]->(b:Function) WHERE b.name = 'main' RETURN a.name, a.file
MATCH (s:Struct)-[:HAS_METHOD]->(m:Method) WHERE s.name = 'Config' RETURN m.name
MATCH (child:Class)-[:EXTENDS]->(parent:Class) RETURN child.name, parent.name

Node types: Package · File · Function · Method · Struct · Interface · Module · Component · Type · Class · Enum · Trait

Edge types: CONTAINS · DEFINES · CALLS · IMPORTS · HAS_METHOD · IMPLEMENTS · USES_COMPONENT · CALLS_API · EXTENDS

recon_list_repos

List all indexed repositories with node/relationship counts and git info.

recon_processes

Detect execution flows by tracing call chains from entry points. Sorted by complexity.

recon_processes(limit?: number, filter?: string)

recon_augment

Compact symbol context for AI augmentation — returns callers, callees, processes, and community in one concise block.

recon_augment(pattern: string)

recon_watcher_status

Get the live status of the file watcher — active state, watched directories, update count, last update, pending queue, and recent errors.

recon_watcher_status()

recon_export

Export the knowledge graph as a Mermaid flowchart or Graphviz DOT diagram. Filterable by package, symbol, node type, and edge type.

recon_export(format?: "mermaid" | "dot", package?: string, symbol?: string, depth?: number, type?: string, edges?: string, limit?: number)

recon_pr_review

Graph-aware PR review — analyzes code changes using the dependency graph to assess blast radius, risk, affected execution flows, and review priorities.

recon_pr_review(scope?: "staged" | "unstaged" | "branch" | "all", base?: string, include_diagram?: boolean)

Risk levels: LOW · MEDIUM · HIGH · CRITICAL — scored by direct callers, confidence tiers, and cross-community impact.

MCP Resources

Structured data via recon:// URIs — agents READ these without making a tool call.

MCP Prompts

Three guided workflows that instruct AI agents step-by-step using Recon's tools:

Each prompt returns a structured message with step-by-step instructions. The agent receives the message and autonomously executes each step using Recon tools.

Dashboard

Start the HTTP server to access the interactive code intelligence dashboard:

recon serve --http  # → http://localhost:3100

Features:

• 🔹 Graph Tab — Force-directed knowledge graph with type-colored nodes, community coloring toggle, and click-to-inspect

• 🔹 Processes Tab — Execution flow viewer with call chains, branch counts, and community tags

• 🔹 Impact Tab — Interactive blast radius analysis with risk levels and confidence tiers

• 🔹 Live Search — Debounced search dropdown (200ms) with keyboard navigation (↑↓ Enter Esc)

• 🔹 Graph Legend — Node type → shape/color mapping

• 🔹 Package Sidebar — Filter graph by package with symbol counts

Multi-Repo Support

Index and query multiple repositories from a single .recon/ directory:

cd /path/to/backend && recon index --repo backend
cd /path/to/frontend && recon index --repo frontend

recon serve                  # Serve all repos (merged graph)
recon serve --repo backend   # Serve single repo

All tools accept an optional repo parameter. Use recon_list_repos to discover indexed repos. Per-repo indices are stored under .recon/repos/{repoName}/.

Search

BM25 Keyword Search

• Tokenizer splits camelCase, PascalCase, snake_case, digit boundaries (base64Decode → ["base", "64", "decode"])

• Name boost — symbol names weighted 3× higher than file paths

• IDF scoring — rare terms rank higher

• Fallback — substring matching when BM25 returns nothing

Hybrid Semantic Search

Enable with recon index --embeddings, then use recon_query({query: "...", semantic: true}).

• Model: Xenova/all-MiniLM-L6-v2 (384-dim embeddings via @huggingface/transformers)

• Fusion: Reciprocal Rank Fusion (RRF) — score = 1/(k + rank), k=60

• Storage: Persisted to .recon/embeddings.json

Architecture

├── src/
│   ├── analyzers/
│   │   ├── ts-analyzer.ts        # TypeScript/React extraction (Compiler API)
│   │   ├── cross-language.ts     # Go route ↔ TS API call matching
│   │   ├── framework-detection.ts # 20+ framework entry point detection
│   │   └── tree-sitter/          # Multi-language tree-sitter analyzer
│   ├── graph/
│   │   ├── graph.ts              # KnowledgeGraph — in-memory Map + adjacency + version
│   │   ├── community.ts          # Label propagation community detection
│   │   └── process.ts            # Execution flow detection (BFS)
│   ├── watcher/
│   │   └── watcher.ts            # Live file watcher — surgical graph updates
│   ├── mcp/
│   │   ├── server.ts             # MCP server (stdio transport)
│   │   ├── tools.ts              # 14 tool definitions (JSON Schema)
│   │   ├── handlers.ts           # Tool dispatch + query logic
│   │   ├── prompts.ts            # 3 MCP prompt templates
│   │   ├── hints.ts              # Next-step hints for agent guidance
│   │   ├── instructions.ts       # AI agent instructions (system prompt)
│   │   ├── augmentation.ts       # Compact context injection
│   │   ├── staleness.ts          # Index freshness check
│   │   ├── rename.ts             # Graph-aware multi-file rename
│   │   └── resources.ts          # MCP Resources (recon:// URIs)
│   ├── search/
│   │   ├── bm25.ts               # BM25 search index
│   │   ├── hybrid-search.ts      # BM25 + vector RRF fusion
│   │   └── vector-store.ts       # In-memory cosine similarity
│   ├── query/
│   │   ├── parser.ts             # Cypher DSL parser
│   │   └── executor.ts           # Query execution + formatting
│   ├── server/
│   │   └── http.ts               # Express HTTP REST API + dashboard
│   ├── dashboard/                # Interactive web dashboard
│   │   ├── index.html
│   │   ├── style.css
│   │   └── app.js
│   └── cli/
│       ├── index.ts              # Commander CLI
│       └── commands.ts           # index, serve, status, clean

Data Flow

  TS Compiler API → components ─┐
  tree-sitter → 13 languages   ├─→ KnowledgeGraph ─→ .recon/graph.json
  router.go → API routes       ─┤   (in-memory)   ─→ .recon/meta.json
  label propagation → clusters ─┤   + BM25 Index   ─→ .recon/search.json
  BFS → execution flows        ─┘   + Communities  ─→ .recon/embeddings.json
                                     + Embeddings
                                     + Processes
                                          │
                                  ┌───────┤
                          File Watcher (chokidar)
                          surgical update ~50ms/file
                                          │
                                ┌─────────┴──────────┐
                           MCP Server (stdio)   HTTP REST API
                         ┌───┴────┐────┐        (:3100 + Dashboard)
                     14 Tools  3 Prompts  5 Resources
                         │        │      recon://packages
                   ┌─────┼────┐   │      recon://symbol/{name}
                   │     │    │   │      recon://file/{path}
                Claude  Cursor …   │      recon://process/{name}
                 Code  Antigravity │      recon://stats
                                  │
                          detect_impact
                          generate_map
                          onboard

HTTP REST API

recon serve --http              # Listen on :3100
recon serve --http --port 8080  # Custom port

# Search for a symbol
curl -X POST http://localhost:3100/api/tools/recon_query \
  -H 'Content-Type: application/json' \
  -d '{"query": "AuthMiddleware"}'

# Read a resource
curl 'http://localhost:3100/api/resources/read?uri=recon://symbol/AuthMiddleware'

CORS enabled by default for browser clients.

Graph Schema

Node Properties

Relationship Types

Testing

npm test           # Run all tests
npx vitest --watch # Watch mode

459 tests across 17 test suites:

Community Detection

After indexing, Recon automatically detects code communities using the Label Propagation Algorithm (LPA):

• Each function/class/struct gets a community label based on its connections

• Communities are named after the most common package in each cluster

• recon_context shows community membership

• recon_impact lists affected communities for cross-module awareness

Live Re-Indexing

Recon watches source files and updates the knowledge graph in real-time:

Incremental Indexing

Files are hashed with SHA-256. On recon index, only changed files are re-analyzed:

• TypeScript: per-file granularity via Compiler API

• Tree-sitter: per-file granularity for all 13 languages

• Auto-detection: serve compares Git commit hashes to detect stale indexes

• Force full re-index with --force

License

MIT