recon-wrxn

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-wrxn fixes this in one line:

npx recon-wrxn 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.

Why recon-wrxn?

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-wrxn 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-wrxn index

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

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

Global install (optional):

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

Requires Node.js ≥ 20. Tree-sitter grammars are bundled as npm dependencies. v6 uses SQLite storage (.recon-wrxn/recon.db) — single file, no JSON sprawl.

Features

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-wrxn 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-wrxn 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-wrxn export --package mcp --limit 20

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

# Filter by node types and edge types
recon-wrxn 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-wrxn automatically → Done.

When your AI agent starts:

1. Agent reads MCP config → runs npx recon-wrxn serve
2. npx downloads recon-wrxn from npm (cached after first run)
3. recon-wrxn auto-indexes the project (cwd) → creates .recon-wrxn/recon.db
4. File watcher starts → monitors source files for changes
5. MCP server opens on stdio (stdin/stdout) — no network, no port
6. Agent sees 8 tools + 3 prompts + 3 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:

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

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

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

Multiple Projects

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

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-wrxn", "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-wrxn", "serve"],
      "cwd": "/path/to/backend"
    },
    "recon-frontend": {
      "command": "npx",
      "args": ["recon-wrxn", "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-wrxn index --repo backend
cd /path/to/frontend && npx recon-wrxn index --repo frontend

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

Then filter by repo in queries: recon_find({query: "Auth", repo: "backend"}).

Auto-Indexing

recon-wrxn serve handles indexing automatically:

Built-in Instructions: recon-wrxn 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-wrxn index                        # Index codebase (incremental)
recon-wrxn index --force                # Force full re-index
recon-wrxn index --repo my-backend      # Index as named repo (multi-repo)
recon-wrxn index --embeddings           # Include vector embeddings for semantic search

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

recon-wrxn export                       # Export graph as Mermaid flowchart (Mermaid only)
recon-wrxn export --symbol handleQuery  # Ego graph around a symbol

recon-wrxn status                       # Show index stats
recon-wrxn status --repo my-backend     # Status for specific repo
recon-wrxn 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-wrxn.json at your project root to persist settings:

// .recon-wrxn.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-wrxn.json, which overrides defaults.

With a config file, your MCP setup stays minimal:

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

No more long args arrays — all config lives in .recon-wrxn.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.

MCP Prompts

Three guided workflows that instruct AI agents step-by-step using recon-wrxn'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-wrxn tools.

Dashboard

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

recon-wrxn 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-wrxn/ directory:

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

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

All tools accept an optional repo parameter. Per-repo indices are stored in .recon-wrxn/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-wrxn 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-wrxn/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-wrxn serve --http              # Listen on :3100
recon-wrxn serve --http --port 8080  # Custom port

# 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

Relationship Types

Testing

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

541 tests across 22 test suites:

Community Detection

After indexing, recon-wrxn 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-wrxn watches source files and updates the knowledge graph in real-time:

Incremental Indexing

Files are hashed with SHA-256. On recon-wrxn 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