{"id":49354101,"url":"https://github.com/bravo1goingdark/recon","last_synced_at":"2026-04-27T12:03:06.886Z","repository":{"id":353593680,"uuid":"1214889269","full_name":"bravo1goingdark/recon","owner":"bravo1goingdark","description":"Token-lean code intelligence MCP server. 20-35x token reduction on code exploration.","archived":false,"fork":false,"pushed_at":"2026-04-24T16:40:42.000Z","size":1043,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T16:41:36.360Z","etag":null,"topics":["ai-agents","ast","claude-code","code-intelligence","code-search","developer-tools","mcp","mcp-server","pagerank","rust","tantivy","tree-sitter"],"latest_commit_sha":null,"homepage":"https://mcprecon.pages.dev/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bravo1goingdark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T07:25:41.000Z","updated_at":"2026-04-24T16:20:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bravo1goingdark/recon","commit_stats":null,"previous_names":["bravo1goingdark/recon"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bravo1goingdark/recon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bravo1goingdark%2Frecon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bravo1goingdark%2Frecon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bravo1goingdark%2Frecon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bravo1goingdark%2Frecon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bravo1goingdark","download_url":"https://codeload.github.com/bravo1goingdark/recon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bravo1goingdark%2Frecon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32335298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ast","claude-code","code-intelligence","code-search","developer-tools","mcp","mcp-server","pagerank","rust","tantivy","tree-sitter"],"created_at":"2026-04-27T12:03:00.537Z","updated_at":"2026-04-27T12:03:06.873Z","avatar_url":"https://github.com/bravo1goingdark.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"site/og.png\" alt=\"recon — 35x fewer tokens for AI coding agents\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003erecon\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Token-lean code intelligence MCP server.\u003cbr/\u003e\n  Replaces \u003ccode\u003eRead\u003c/code\u003e, \u003ccode\u003eGrep\u003c/code\u003e, and \u003ccode\u003eGlob\u003c/code\u003e with symbol-aware tools that deliver \u003cstrong\u003e15-30x token reduction\u003c/strong\u003e on code exploration.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://mcprecon.pages.dev\"\u003eWebsite\u003c/a\u003e · \u003ca href=\"https://mcprecon.pages.dev/Docs.html\"\u003eDocs\u003c/a\u003e · \u003ca href=\"#connect-your-agent-hosted\"\u003eGet Started\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nOffered as a **hosted MCP server** -- no binary to install, no local indexing. Point your agent at the endpoint, hand it an API key, and it gets 12 symbol-aware tools instantly.\n\n## Benchmarks\n\nMeasured on real codebases, release build, warm cache:\n\n| | Zed (80K symbols) | Rust compiler (320K symbols) |\n|---|---|---|\n| **stats** | 10 ms | 29 ms |\n| **find** | 8 ms | 8 ms |\n| **search** | 11 ms | 33 ms |\n| **outline** | 14 ms | 13 ms |\n| **skeleton** | 11 ms | 11 ms |\n| **refs** | 8 ms | 12 ms |\n| **map (cached)** | 8 ms | 19 ms |\n| **map (cold)** | 405 ms | 2.0 s |\n| **cold index** | 19 s | 53 s |\n\nAll read-path queries under 33 ms on 320K symbols. Binary size: 24 MB.\n\n## Token reduction\n\nMeasured on the Rust compiler (318K symbols), recon vs Read/Grep/Glob:\n\n| Scenario | Before | After | Reduction |\n|---|---|---|---|\n| Read one function | ~23,838 tok | ~111 tok | **215x** |\n| Find a symbol | ~17,500 tok | ~226 tok | **77x** |\n| Repo orientation | ~52,500 tok | ~2,170 tok | **24x** |\n| Find references | ~15,000 tok | ~638 tok | **24x** |\n| Outline a file | ~23,838 tok | ~1,350 tok | **18x** |\n| Understand a file | ~23,838 tok | ~6,412 tok | **3.7x** |\n\nA typical \"find and fix a bug\" task: **~3.2K tokens** with recon vs **~100K+** with Read/Grep/Glob.\n\n## Connect your agent (hosted)\n\n### Step 1: Get an API key\n\nContact us to get a server key for your workspace.\n\n### Step 2: Add to your MCP config\n\nDrop this into `.mcp.json` at your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"recon\": {\n      \"url\": \"https://mcp.recon.dev/v1\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Step 3: Teach your agent\n\nAdd this to your `CLAUDE.md` (or equivalent agent system prompt):\n\n```markdown\nPrefer code_* tools (code_outline, code_skeleton, code_find_symbol,\ncode_search, code_repo_map) over Read/Grep/Glob for code exploration.\nThey return structured, token-efficient results.\n```\n\n### Step 4: Restart your agent\n\nRestart Claude Code (or your MCP client). The 12 `code_*` tools are now available. Indexing, watching, and ranking all run server-side.\n\n## Setup\n\n```bash\n# 1. Authenticate once per machine (caches license globally)\nrecon login sk-recon-your-key\n\n# 2. In each project: index + set up IDE MCP config\nrecon init --mcp cc        # Claude Code  (.mcp.json)\nrecon init --mcp oc        # OpenCode     (.opencode/mcp.json)\nrecon init --mcp cursor    # Cursor       (.cursor/mcp.json)\nrecon init --mcp windsurf  # Windsurf     (.windsurf/mcp.json)\nrecon init                 # Index only, no MCP config\n\n# Your IDE auto-starts recon serve — you never run it manually.\n```\n\nOther license commands:\n\n```bash\nrecon license    # show cached tier, limits, expiry\nrecon logout     # remove cached license\n```\n\n## Tools (12)\n\n| Tool | Replaces | What it does | Latency |\n|---|---|---|---|\n| `code_outline(path)` | Read | One line per symbol -- kind, name, line | 13 ms |\n| `code_skeleton(path)` | Read | Signatures + docs, bodies as `...` (10x compression) | 11 ms |\n| `code_read_symbol(path, symbol)` | Read | Full source of one symbol + callers | \u003c10 ms |\n| `code_find_symbol(name)` | Grep | 3-tier: exact SQLite -\u003e Tantivy BM25 -\u003e FTS5 + nucleo fuzzy | 8 ms |\n| `code_find_refs(symbol)` | Grep | Reference count + top-k call sites | 12 ms |\n| `code_search(query, mode, filter?)` | Grep | exact/regex/hybrid + filter DSL, Tantivy-first | 33 ms |\n| `code_list(glob?, lang?, filter?)` | Glob | Structured file listing with symbol counts (batch query) | 57 ms |\n| `code_repo_map(budget)` | -- | PageRank-ranked symbol overview, cached in SQLite | 19 ms |\n| `code_find_strings(pattern)` | -- | Search string literals and comments | \u003c30 ms |\n| `code_multi_find(patterns[])` | -- | Multi-pattern search in one call | \u003c30 ms |\n| `code_reindex()` | -- | Agent-triggered re-indexing, clears map cache | varies |\n| `code_stats()` | -- | Index health: files, symbols, freshness | 10 ms |\n\n### Filter DSL\n\nSearch tools accept an optional `filter` parameter:\n\n```\n*.rs                   # extension filter\ntype:rust              # language type\nstatus:modified        # git-modified files only\n!test                  # exclude paths containing \"test\"\n/src/                  # path segment match\n```\n\n## Architecture\n\n```\ncrates/\n  recon-core/       # Types, errors, 5 output shapes, config, secret redaction\n  recon-parser/     # Tree-sitter pools (9 langs), symbol extraction\n  recon-storage/    # SQLite + FTS5 trigram, blake3, batch inserts\n  recon-search/     # Tantivy BM25, fff-grep, nucleo fuzzy, PageRank, token counting\n  recon-embed/      # fastembed + LanceDB vector search (feature-gated)\n  recon-indexer/    # Merkle tree, gix ColdStart, file watcher, rayon parallel parse\n  recon-server/     # rmcp MCP handler, 12 tools, parking_lot Mutex, redaction\n  recon-cli/        # CLI: login, init, serve, index, purge, query tools\n```\n\n### Search tiers\n\n| Tier | Backend | Latency |\n|---|---|---|\n| T0 -- Symbol exact | SQLite btree index | \u003c1 ms |\n| T1 -- Symbol fuzzy | SQLite FTS5 trigram + nucleo rescore | 2-8 ms |\n| T2 -- Structured BM25 | Tantivy with CodeSplitTokenizer | 5-15 ms |\n| T3 -- Raw text/regex | fff-grep (SIMD + memmap2) | 3-95 ms |\n| T4 -- Semantic | fastembed + LanceDB (feature-gated) | 50-150 ms |\n\n### Incremental indexing\n\n1. **ColdStart** -- gix reads HEAD SHA. If unchanged since last index, skip entirely.\n2. **Merkle diff** -- blake3 hash tree. On HEAD change, reindex only changed files.\n3. **Full index** -- first run, parallel parse via rayon.\n4. **Live watcher** -- notify-debouncer-full (250 ms debounce) triggers per-file reindex.\n\n### PageRank repo map\n\n`code_repo_map` builds a directed graph from symbol references, applies Aider-style edge weights (10x long identifiers, 0.1x private names, 50x focus files), runs power iteration with early convergence, and renders the top-ranked symbols within a token budget. Result is cached in SQLite, keyed on `max(indexed_at)` -- invalidates automatically on any reindex.\n\n## Performance engineering\n\n- **mimalloc** global allocator\n- **parking_lot::Mutex** instead of tokio::sync::Mutex (no async overhead on sync SQLite)\n- **DashMap** for multi-tenant repo routing (sharded RwLock, zero contention on reads)\n- **Fat LTO + panic=abort + opt-level=3** -- 24 MB binary\n- **SQLite tuning** -- WAL, mmap 256MB, cache 32MB, PRAGMA optimize, chunked bulk inserts (500 files/tx)\n- **Tantivy-first search** -- try BM25 index before falling back to grep, 50MB heap, commits every 20K docs\n- **Token heuristic** -- estimate_tokens (len/4) in hot loops, tiktoken for accuracy checks\n- **Map caching** -- PageRank cached in SQLite meta, invalidated on max(indexed_at) change\n- **Early convergence** -- PageRank stops when L1 norm delta \u003c 1e-6 (typically 8-12 iterations)\n- **ahash::AHashMap** -- non-cryptographic hash in PageRank and RRF fusion hot paths\n- **Bulk SQL** -- all_symbols() and all_refs() single-query loads for PageRank\n- **Secret redaction** -- regex scanner on all tool responses returning code content\n- **Path traversal guard** -- canonicalize + prefix check, repo root cached\n- **Stdout hygiene** -- all logging to stderr, verified by CI test\n\n## Testing\n\n```bash\ncargo test --workspace           # 107 tests across 19 suites\ncargo clippy --workspace -- -D warnings\n```\n\n- Zero `unwrap()` in production library code\n- `#[deny(missing_docs)]` on all 7 crate roots\n- Secret redaction on all code-returning tool responses\n- Stdout hygiene subprocess test\n- Self-host E2E (index this repo, verify symbols)\n- Incremental E2E (cold index, HEAD skip, merkle diff, delete cascade)\n- Tool description length enforcement (\u003c2 KB each)\n\n## ADRs\n\n- [000 -- Symbol-first architecture](docs/adr/000-symbol-first-architecture.md)\n- [001 -- Text search backend](docs/adr/001-text-search-backend.md)\n- [002 -- Output shape discipline](docs/adr/002-output-shape-discipline.md)\n- [003 -- Stdio transport hygiene](docs/adr/003-stdio-transport-hygiene.md)\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbravo1goingdark%2Frecon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbravo1goingdark%2Frecon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbravo1goingdark%2Frecon/lists"}