01 — Tools

Twelve tools that speak symbols, not strings.

code_outline(path)

↳ Read

One line per symbol — kind, name, line. Skim a 2000-line file in a single screen.

13 ms

code_skeleton(path)

↳ Read

Signatures and docs only; bodies collapse to …. About 10× compression vs. full read.

11 ms

code_read_symbol(…)

↳ Read

Pull a single function, its signature, doc, body — and every caller — without loading the file.

<10 ms

code_find_symbol(name)

↳ Grep

Three-tier resolver: exact SQLite → Tantivy BM25 → FTS5 trigram with nucleo fuzzy rescore.

8 ms

code_find_refs(…)

↳ Grep

Reference count and the top-k call sites for any symbol in the repo.

12 ms

code_search(query, mode)

↳ Grep

Exact · regex · hybrid. Tantivy-first, grep fallback. Filter DSL: type:rust !test.

33 ms

code_list(glob?)

↳ Glob

Structured file listing with symbol counts — single GROUP BY query, not per-file.

57 ms

code_repo_map(budget)

—

PageRank-ranked repo overview, cached in SQLite, invalidated on reindex.

19 ms

code_find_strings(…)

—

Search string literals and comments separately from identifiers. Grep, but narrower.

<30 ms

code_multi_find(patterns[])

—

Fan out several patterns through the TextSearcher trait in a single call.

<30 ms

code_reindex()

—

Agent-triggered re-index. Clears map cache, rebuilds incrementally.

varies

code_stats()

—

Index health: files, symbols, tantivy docs, freshness.

10 ms

02 — The difference

An agent reading code shouldn't burn the context window doing it.

Without recon Read · Grep · Glob

// agent wants to understand render_map
Read("crates/recon-search/src/map.rs")
→ 412 lines  ·  ~6,800 tokens

Grep("render_map", "crates/**")
→ 34 matches  ·  ~2,100 tokens

Read("crates/recon-search/src/page_rank.rs")
→ 218 lines  ·  ~3,600 tokens

subtotal ≈ 109,000 tokens

tokens burned109,000

With recon code_*

// same question, symbol-first
code_find_symbol("render_map")
→ 1 hit, 3 ranked callers  ·  ~140 tokens

code_read_symbol("…/map.rs", "render_map")
→ body + 7 call sites  ·  ~780 tokens

code_skeleton("…/page_rank.rs")
→ signatures + docs  ·  ~340 tokens

subtotal ≈ 3,100 tokens

tokens burned3,100 · ~35× less

03 — Principles

Built on four small, stubborn ideas.

Symbols first, bytes last.

Everything tree-sitter can name is a first-class citizen. Everything else is noise the agent should never pay for.

Five output shapes. No more.

Every tool response is one of five canonical shapes in recon-core::shapes. Predictable for the model, cheap to parse.

III

Incremental by default.

gix ColdStart skips reparse on unchanged HEAD. A blake3 Merkle tree reindexes only what moved. First keystroke to queryable: under a second.

Secrets stay redacted.

Every tool response passes through secret redaction — AWS keys, PEM blocks, API tokens are stripped before they reach the agent. Per-key tenant isolation.

04 — Benchmarks

Tested on real codebases. Not toy repos.

Zed

EDITOR · RUST

github →

LOC
1.3M

SYMBOLS
80K

COLD INDEX
19_s

QUERY P50
8_ms

find 8ms outline 14ms skeleton 11ms search 11ms refs 8ms map 8ms

Rust compiler

COMPILER · RUST

github →

LOC
3.8M

SYMBOLS
320K

COLD INDEX
53_s

QUERY P50
10_ms

find 8ms outline 13ms skeleton 11ms search 33ms refs 12ms map 19ms

All numbers: release build · warm cache · mimalloc · fat LTO · parking_lot::Mutex · ahash · 24 MB binary

05 — Connect

A hosted MCP server. No install, no binary.

Step 01

Grab an API key

# your key looks like this
RECON_KEY=rk_live_9f2c…

Step 02

Point your agent at the server

Drop this into your agent's MCP config. That's the whole setup — no local indexing, no watcher, no build step.

{
  "mcpServers": {
    "recon": {
      "url": "https://mcp.recon.dev/v1",
      "headers": {
        "Authorization": "Bearer $RECON_KEY"
      }
    }
  }
}

Step 03

Teach your agent

One line in your agent's system prompt reorders its habits toward the code_* tools.

# agent rules
Use code_* tools (outline, skeleton,
find_symbol, search, repo_map) before
Read/Grep/Glob when exploring code.

Step 04

Query from anywhere

Use rr — the open-source CLI client — to query your repos from the terminal. Or let your MCP agent handle it.

# install the public CLI
cargo install rr

# query your hosted repos
rr find TyCtxt
rr map --budget 2000
rr outline src/main.rs