Recon

Give your AI agent a brain. Index your codebase in 5 seconds.
_{A code intelligence MCP server — 8 tools, 13 languages, knowledge graph, zero config.}

TL;DR · Quick Start · Features · MCP Setup · Tools · Dashboard

TL;DR

Your AI agent is blind to architecture. It greps, it guesses, it breaks things in files it never read.

Recon fixes this in one line:

npx recon-mcp serve

That's it. Your agent now has a knowledge graph of your entire codebase:

Ask "what breaks if I change this function?" — blast radius in ms
"Trace execution flow from this API route" — cross-language call chain
"Find code structurally similar to X" — hybrid FTS5 + vector search
"Safely rename this across the repo" — graph-aware, no false positives
"Draw me an architecture diagram" — Mermaid, one command
"Find dead code and circular deps" — code quality rules
"Which tests are affected?" — test impact analysis

Works with Claude Code, Cursor, Windsurf and any MCP client. Zero config. 13 languages. MIT.

2026-03-20.015541.mp4

Why Recon?

AI coding agents are blind to architecture. They read one file at a time, grep for identifiers, guess at call sites, and break things in places they never saw.

You can't fix this with a bigger context window. You need structure.

Recon indexes your codebase into a knowledge graph — functions, classes, call chains, imports, communities — and exposes it through 8 MCP tools, 3 prompts, and 3 resources that any AI agent can query.

One command, full awareness. Your agent gets dependency mapping, blast radius analysis, safe renames, execution flow tracing, natural language search, and code quality analysis — 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. v6 uses SQLite storage (.recon/recon.db) — single file, no JSON sprawl.

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
Code quality analysis — dead code, circular deps, unused exports
Test impact analysis — affected tests per change

Search & Query

FTS5 full-text search — camelCase/snake_case tokenization with relevance ranking
Natural language search — find symbols by description, not just exact names
Hybrid semantic search — vector embeddings (all-MiniLM-L6-v2) + RRF fusion
MCP Resources — recon:// URIs for symbols, files, 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 to SQLite on every update, survives restarts
Graph export — Mermaid flowchart, filterable by package/symbol/type

Supported Languages

Language	Analyzer	What's indexed
Go	Tree-sitter + dedicated	Packages, functions, methods, structs, interfaces, call graph, imports
TypeScript	Dedicated (Compiler API)	Modules, components, functions, types, JSX usage, imports
Python	Tree-sitter	Classes, functions, methods, inheritance, imports, calls
Rust	Tree-sitter	Structs, enums, traits, functions, impl blocks, use imports, calls
Java	Tree-sitter	Classes, interfaces, enums, methods, imports, calls
C	Tree-sitter	Functions, structs, enums, macros, #include imports, calls
C++	Tree-sitter	Classes, structs, namespaces, enums, functions, inheritance, calls
Ruby	Tree-sitter	Classes, modules, methods, inheritance, require imports, calls
PHP	Tree-sitter	Classes, interfaces, functions, methods, use imports, calls
C#	Tree-sitter	Classes, interfaces, enums, methods, using imports, calls
Kotlin	Tree-sitter (optional)	Classes, interfaces, enums, functions, import declarations, calls
Swift	Tree-sitter (optional)	Classes, structs, enums, functions, import declarations, calls
Cross-language	Route matching	HTTP API routes mapped from Go handlers to TypeScript consumers

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 FTS5 full-text 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 FTS5 + 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):

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

# Ego graph around a symbol
recon export --symbol handleQuery --depth 2

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

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

How It Works

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

When your AI agent starts:

Agent reads MCP config → runs npx recon-mcp serve
npx downloads Recon from npm (cached after first run)
Recon auto-indexes the project (cwd) → creates .recon/recon.db
File watcher starts → monitors source files for changes
MCP server opens on stdio (stdin/stdout) — no network, no port
Agent sees 8 tools + 3 prompts + 3 resources
Agent receives built-in instructions → knows when to use each tool
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 queryable from a single MCP server. Use the repo parameter on any tool to filter by project.

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_find({query: "Auth", repo: "backend"}).

Auto-Indexing

recon serve handles indexing automatically:

Scenario	Behavior
First run (no `.recon/`)	Full index → creates `.recon/recon.db`
Code changed since last index	Incremental re-index (only changed files)
No changes	Uses cached index → instant startup
Force re-index	`recon index --force`
Skip auto-index	`recon serve --no-index`
Index but no watcher	`recon serve --no-watch`

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_explain 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 (Mermaid only)
recon export --symbol handleQuery  # Ego graph around a symbol

recon status                       # Show index stats
recon status --repo my-backend     # Status for specific repo
recon clean                        # Delete index

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.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
  "crossLanguage": true,         // Enable cross-language API matching
  "testPatterns": ["**/*.test.*", "**/*.spec.*"],  // Test file patterns
  "rules": {                     // Code quality rule config
    "deadCode": true,
    "circularDeps": true,
    "unusedExports": true
  }
}

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 8 tools accept an optional repo parameter for multi-repo filtering.

recon_map

Architecture overview: packages, tech stack, entry points, health.

recon_map(repo?: string)

recon_find

Smart search: exact name, wildcard (*Handler), or natural language.

recon_find(query: string, type?: string, language?: string, package?: string, limit?: number)

recon_explain

Full 360° context: callers, callees, flows, cross-language links, tests.

recon_explain(name: string, file?: string, depth?: number, include_source?: boolean)

recon_impact

Blast radius analysis with affected tests.

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

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

recon_changes

Git diff to affected symbols, risk assessment, and affected tests.

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

recon_rename

Graph-aware safe rename across files. Dry-run by default.

recon_rename(symbol: string, new_name: string, file?: string, dry_run?: boolean)

recon_export

Generate Mermaid diagram.

recon_export(target?: string, scope?: string, depth?: number, direction?: string, limit?: number)

recon_rules

Code quality: dead code, circular deps, unused exports, large files, orphans.

recon_rules(rule?: string, package?: string, language?: string)

MCP Resources

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

Resource	URI	Description
Index Stats	`recon://stats`	Node and relationship counts by type and language
Symbol Detail	`recon://symbol/{name}`	Symbol definition, callers, callees, relationships
File Symbols	`recon://file/{path}`	All symbols in a file with types and line ranges

MCP Prompts

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

Prompt	Description	Usage
`pre_commit`	Pre-commit change analysis → risk report	`pre_commit(scope: "staged")`
`architecture`	Architecture documentation with mermaid diagrams	`architecture()`
`onboard`	New developer onboarding guide	`onboard(focus: "auth")`

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. Per-repo indices are stored in .recon/recon.db.

Search

FTS5 Full-Text Search

FTS5 replaces custom BM25, with camelCase/snake_case tokenization built into SQLite.

Tokenizer splits camelCase, PascalCase, snake_case, digit boundaries (base64Decode → ["base", "64", "decode"])
Name boost — symbol names weighted 3x higher than file paths
Ranking — FTS5 rank function with relevance scoring
Fallback — substring matching when FTS5 returns nothing

Hybrid Semantic Search

Enable with recon index --embeddings, then use recon_find({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 in recon.db

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              # 8 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/
│   │   ├── fts5.ts               # FTS5 full-text search
│   │   ├── hybrid-search.ts      # FTS5 + vector RRF fusion
│   │   └── vector-store.ts       # In-memory cosine similarity
│   ├── 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/recon.db (SQLite)
  router.go → API routes       ─┤   (in-memory)       single database:
  label propagation → clusters ─┤   + FTS5 Index       - nodes, relationships
  BFS → execution flows        ─┘   + Communities      - search index (FTS5)
                                     + Embeddings       - embeddings
                                     + Processes        - metadata
                                          │
                                  ┌───────┤
                          File Watcher (chokidar)
                          surgical update ~50ms/file
                                          │
                                ┌─────────┴──────────┐
                           MCP Server (stdio)   HTTP REST API
                         ┌───┴────┐────┐        (:3100 + Dashboard)
                      8 Tools  3 Prompts  3 Resources
                         │        │      recon://symbol/{name}
                   ┌─────┼────┐   │      recon://file/{path}
                   │     │    │   │      recon://stats
                Claude  Cursor …   │
                 Code  Antigravity │
                                  │
                          pre_commit
                          architecture
                          onboard

HTTP REST API

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

Method	Path	Description
`GET`	`/api/health`	Health check + index stats
`GET`	`/api/tools`	List available tools with schemas
`POST`	`/api/tools/:name`	Execute a tool (body = JSON params)
`GET`	`/api/resources`	List MCP resources + templates
`GET`	`/api/resources/read?uri=...`	Read resource by URI

# Search for a symbol
curl -X POST http://localhost:3100/api/tools/recon_find \
  -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.

Security: HTTP server binds to localhost (127.0.0.1) by default. Use --host 0.0.0.0 to expose on network.

Graph Schema

Node Properties

Property	Type	Description
`id`	`string`	Unique node identifier
`type`	`NodeType`	Function, Method, Struct, Interface, Class, etc.
`name`	`string`	Symbol name
`file`	`string`	Source file path
`startLine` / `endLine`	`number`	Line range in file
`language`	`Language`	Source language
`package`	`string`	Package/module path
`exported`	`boolean`	Whether the symbol is exported
`repo`	`string?`	Repository name (multi-repo)
`community`	`string?`	Community/cluster label (auto-detected)
`isTest`	`boolean?`	Whether the symbol is in a test file

Relationship Types

Type	Meaning	Confidence
`CONTAINS`	Package/Module → File	1.0
`DEFINES`	File → Symbol	1.0
`CALLS`	Function → Function	0.5–1.0
`IMPORTS`	Package → Package / File → File	1.0
`HAS_METHOD`	Struct/Class → Method	1.0
`IMPLEMENTS`	Struct → Interface / Class → Trait	0.8–0.9
`EXTENDS`	Class → Class (inheritance)	0.9
`USES_COMPONENT`	Component → Component (JSX)	0.9
`CALLS_API`	TS Function → Go Handler (cross-language)	0.85–0.95

Testing

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

541 tests across 22 test suites:

Suite	Tests	Coverage
`graph.test.ts`	23	KnowledgeGraph API — add, query, remove, serialize
`handlers.test.ts`	30	MCP tool dispatch with mock graph
`search.test.ts`	27	FTS5 tokenizer, ranking, serialization
`rename.test.ts`	28	Graph-aware rename, disambiguation, formatting
`resources.test.ts`	35	Resource URI parsing, all 3 resource types
`tree-sitter.test.ts`	58	Multi-language extraction, cross-language consistency
`multi-repo.test.ts`	16	Multi-repo storage, filtering
`community.test.ts`	13	Label propagation clustering, handler integration
`embeddings.test.ts`	39	Vector store, RRF fusion, hybrid search
`process.test.ts`	21	Execution flow detection, BFS, cycles
`http.test.ts`	18	HTTP REST API routes, CORS
`framework-detection.test.ts`	27	Path/name framework detection, multipliers
`augmentation.test.ts`	28	Augmentation engine, staleness check, MCP prompts
`sqlite.test.ts`	32	SQLite storage, migrations, FTS5 indexing
`find.test.ts`	24	Smart search — exact, wildcard, natural language
`rules.test.ts`	29	Dead code, circular deps, unused exports, orphans
`errors.test.ts`	18	Error handling, edge cases, graceful degradation
`migrate.test.ts`	15	JSON-to-SQLite migration, data integrity

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_explain 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:

Feature	Detail
File watcher	chokidar v4 with 1.5s debounce, `awaitWriteFinish` for atomic writes
Surgical update	Remove old nodes → re-parse single file → insert new nodes + edges
Speed	~50ms per file change
TS files	Full re-analysis: symbols, imports, calls, JSX components
Tree-sitter files	Full re-analysis: symbols, calls, heritage, methods (Python, Rust, Java, etc.)
Edge reconstruction	CALLS, IMPORTS, HAS_METHOD, EXTENDS, IMPLEMENTS, USES_COMPONENT
Incoming callers	Automatically re-linked after update
FTS5 index	Auto-updated in SQLite on every graph change
Multi-project	`--projects` flag watches additional directories
Ignored	`node_modules/`, `.git/`, `dist/`, `.next/`, `build/`, `coverage/`

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

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.github/workflows		.github/workflows
bin		bin
src		src
test/unit		test/unit
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
recon.config.example.json		recon.config.example.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Recon

TL;DR

Why Recon?

Quick Start

Features

Code Intelligence

Search & Query

Supported Languages

Enhanced Search (Optional)

Graph Export

How It Works

MCP Integration

Single Project

Multiple Projects

Auto-Indexing

CLI Commands

Configuration

Tool Reference

recon_map

recon_find

recon_explain

recon_impact

recon_changes

recon_rename

recon_export

recon_rules

MCP Resources

MCP Prompts

Dashboard

Multi-Repo Support

Search

FTS5 Full-Text Search

Hybrid Semantic Search

Architecture

Data Flow

HTTP REST API

Graph Schema

Node Properties

Relationship Types

Testing

Community Detection

Live Re-Indexing

Incremental Indexing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages