# radar
**A fast, local repository router for coding agents and humans.**
radar compiles a repository into small committed `MAP.md` routers and a
disposable local query index. A consumer can resolve a task to an exact source
anchor without repeatedly searching or rereading the whole tree.
The default path is deterministic and LLM-free. It needs no API key, network
request, daemon, vector database, or model download.
See [BENCHMARKS.md](BENCHMARKS.md) for the latest reproducible measurements,
[OPTIMIZATIONS.md](OPTIMIZATIONS.md) for every accepted or rejected proposal,
and [ARCHITECTURE.md](ARCHITECTURE.md) for the implementation contract.
The public product page is [radar.sanixdk.xyz](https://radar.sanixdk.xyz/).
Its dependency-free source and generic Caddy deployment example live in
[`site/`](site/).
## Performance highlights
### Local processing on 10,000 generated source files
Every row below uses zero model calls and zero model tokens. The source-packet
row is from a separate concurrently loaded host run; default-path isolation is
reported through paired same-host A/B measurements in `BENCHMARKS.md`.
| Path | p95 latency | Result |
|---|---:|---|
| Fresh process, lexical query | 28.74 ms | exact source anchor |
| Fresh process, verified learned route | 35.97 ms | exact source anchor |
| Fresh process, verified source packet | 18.85 ms | exact definition body |
| First resident lexical query | 3.03 ms | cold in-process lookup |
| Repeated resident lexical query | 0.035 ms | bounded exact-answer cache |
| Repeated resident exact route | 0.040 ms | bounded exact-answer cache |
| Resident unknown-query fallback | 0.150 ms | 244-byte bounded metadata hint |
The resident server starts in 20.83 ms and uses about 14.0 MiB RSS. Its single
tool schema is 387 bytes. A persisted 3.28 MB query snapshot reduced server
startup from 139.57 ms to 21.72 ms and cold lexical p95 from 185.93 ms to
60.63 ms before the final routing refinements.
### Deterministic routing quality on radar's source tree
The separate quality corpus runs 40 source-location questions against radar's
current source tree. It retrieves the expected anchor in the first three
results for 40/40 cases and ranks it first for 34/40 on the refreshed current
tree. Five fresh processes per case produce an 8.90 ms p95 and 881 estimated response tokens
across all 40 final responses.
The latest scorer-heavy gate cut fresh-query p50 by 14.65% to 25.90% and p95
by 9.82% to 23.21% without changing top-three retrieval quality.
For implementation questions, `radar query --source` verifies the current file
hash and returns only the enclosing definition under a 12 KiB cap. Across six
locked Spark tasks, this reduced the sum of uncached-input medians from 5,698
to 2,261 (60.3%) with 18/18 correct answers in both arms.
### Live navigation before and after radar
The live harness uses the locked `gpt-5.3-codex-spark` navigator with low
reasoning and three isolated runs per task. `Before` lets the navigator search
source directly. `After` gives it one exact `radar query` command and requires
the command output verbatim.
| Project scale and task | Before input | After input | Change |
|---|---:|---:|---:|
| 12 files, exact storage location | 994 | 592 | 1.68x fewer |
| 12 files, caller trace | 900 | 657 | 1.37x fewer |
| 12 files, subsystem orientation | 3,935 | 634 | 6.21x fewer |
| 300 files, cold literal lookup | 766 | 611 | 1.25x fewer |
| 300 files, semantic package hub | 3,733 | 574 | 6.50x fewer |
| 300 files, deep semantic package hub | 4,517 | 596 | 7.58x fewer |
| 800 files, cold literal lookup | 562 | 585 | 4.1% higher |
| **Sum of task medians** | **15,407** | **4,249** | **72.4% lower** |
The direct-query arm was correct in 21/21 runs. Direct source search was
correct in 20/21. The local radar process itself consumes zero model tokens;
the remaining live input is navigator overhead for invoking and returning one
command result.
The one cold 800-file literal query is intentionally visible. Radar is most
valuable when repository size, path depth, ambiguity, or semantic wording make
direct search expensive. Tiny or obvious literal searches can already be
cheap.
Applying the published
[GPT-5.3-Codex API rates](https://developers.openai.com/api/docs/models/gpt-5.3-codex)
as a reference scenario reduces the sum of per-task median costs by 63.7%.
This is not claimed as billed Spark spend because Spark remains a research
preview with non-final credit rates.
## Comparison with nearby open-source alternatives
These products overlap in repository understanding but are not identical
benchmarks. The table keeps each project's own published numbers labeled as
such; only radar's rows are reproduced in this repository. The fairest direct
comparison is the deterministic source-anchor corpus in
[BENCHMARKS.md](BENCHMARKS.md), not a rival's headline token percentage.
| Project | Primary shape | Published or reproduced result | Where radar is ahead / boundary |
|---|---|---|---|
| **[Aider repo map](https://github.com/Aider-AI/aider)** | Model-side repository map integrated into an AI coding loop | **Project-documented:** tree-sitter definitions plus dependency/PageRank ranking, selected to a configurable map-token budget (default 1k) | Radar emits committed routers and exact source anchors without a model call; Aider is stronger as an interactive editor that continuously adapts context to chat state. |
| **[radar](https://github.com/Sanix-Darker/radar)** | Committed `MAP.md` routers, zero-model CLI, optional one-tool MCP | **Reproduced:** 28.74 ms fresh-query p95 and 0.035 ms repeated resident p95 on 10,000 generated files; 40/40 top-3 source-anchor retrieval; zero model/runtime dependencies | Deterministic, source-verifiable answers, bounded output, crash-safe derived caches, and no daemon or network. It is intentionally a navigation layer, not an editor or hosted review service. |
| **[code-review-graph](https://github.com/tirth8205/code-review-graph)** | Persistent AST graph, blast-radius analysis, PR review action, MCP/CLI | **Project-reported:** 40.3 s full build for 2,998 files; 9.8 s two-file full update; 2.4 to 2.9 s hook-path update. **Radar clean-room smoke:** 0.056 s map build, 0.060 s refresh, 2.729 ms fresh route p50 on the same 300-file Python subject | Radar was 37.1x faster to build and 9.3x faster to refresh in the dated smoke run, with a 67-byte verified anchor. Code-review-graph is stronger for review-specific impact prediction and broader language coverage; those are not the same task. |
| **[TokenSave](https://github.com/aovestdipaperino/tokensave)** | Persistent semantic graph, 80+ tools, 50+ languages, agent hooks and editing tools | **Project-reported:** 1.2 s full index on 1,782 files / 57k nodes / 103k edges. **Radar corpus:** radar retrieved 40/40 cases in top-3 versus 5/40 for the TokenSave context command; TokenSave timing was excluded because its binary required a different glibc environment | Radar wins the narrow, deterministic source-location contract with one bounded answer and eight core runtime dependencies. TokenSave is broader for semantic context, edits, branch indexes, and agent integrations. |
| **[Semble](https://github.com/MinishLab/semble)** | CPU code search using static embeddings + BM25, CLI/MCP | **Project-reported:** ~500 ms average indexing, ~1 ms query, NDCG@10 0.854, ~99% fewer tokens than grep+read | Radar's resident lookup is lower on its own measured workload and its result is a verified anchor rather than a code snippet. Semble is stronger for semantic chunk retrieval and remote-repository search; the quality corpora differ. |
| **[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)** | Persistent knowledge graph, 15 MCP tools, broad parser surface | **Project-reported:** 158 languages, sub-ms structural queries, 83% answer quality, 10× fewer tokens and 2.1× fewer tool calls across 31 repositories | Radar has a smaller auditable surface, committed human-readable artifacts, strict deterministic tests, and no service/runtime dependency. The language-count and answer-quality claims are not rerun by radar. |
| **[CodeGraph](https://github.com/suatkocar/codegraph)** | Native Rust semantic graph, vector search, hooks, MCP | **Project-reported:** 32 languages, 44 tools, sub-second indexing, and ~12 ms no-change session re-index | Radar uses a compact lexical index with no vector runtime, exposes one read-only tool, and measures exact-answer quality. CodeGraph is broader for graph/security/data-flow tools. |
| **[Repomix](https://github.com/yamadashy/repopack)** | Packs a selected repository into one AI-friendly file | No comparable retrieval benchmark; its product is whole-repository packaging rather than indexed routing | Radar avoids shipping the whole corpus and returns bounded anchors; Repomix remains useful when a complete portable snapshot is the desired input. |
| **[RepoWise](https://github.com/repowise-dev/repowise)** | Graph + git history + generated docs + health/decision intelligence | **Project-reported:** designed for under 30 s on a 3,000-file repo, with nine MCP tools and incremental updates under 30 s | Radar is lighter, deterministic, and zero-LLM by default. RepoWise is stronger when code health, ownership, decisions, and git-history intelligence matter. |
The result is a measurable lead on radar's chosen axis: fast, local,
deterministic, source-verifiable navigation, without pretending that a review
graph, semantic search engine, whole-repo packer, and code-health platform are
interchangeable. Re-run the radar commands in [BENCHMARKS.md](BENCHMARKS.md)
before quoting any cross-project number; competitor figures above can change
with their releases and hardware.
## How it works
radar moves deterministic repository work out of the model loop:
1. Scan supported source files and extract definitions and references once.
2. Rank files and symbols with a compact integer graph.
3. Emit budgeted `MAP.md` routers plus verified route and symbol indexes.
4. Persist a disposable query snapshot for fast process startup.
5. Resolve a complete task with `radar query` or the optional resident MCP
server.
For review triage, `radar impact --since REV --history` adds bounded,
first-parent co-change evidence. It is explicitly correlational and isolated
from ordinary map/query identity; bulk commits are ignored so an initial import
does not masquerade as useful knowledge.
Exact routes and source indexes are checked before map fallback. Fallback
routing reads bounded `MAP.md` frontmatter heads, not complete map files.
Source remains authoritative.
### Open Knowledge Format
Every generated `MAP.md` is an OKF-compatible concept document: Git-native
Markdown with YAML frontmatter, including a descriptive `type`, `title`, and
`description`. OKF is Google's open, vendor-neutral format for portable
knowledge bases and is designed to be readable by people, deterministic tools,
and agents. Radar adds its routing fields as producer-defined metadata while
keeping the source tree authoritative. See the
[Open Knowledge Format specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
This is format compatibility, not a claim that radar implements OKF's optional
provenance, lifecycle, or attestation families.
## Install from a release
GitHub Releases are configured for six targets:
- `linux-x86_64`
- `linux-aarch64`
- `macos-x86_64`
- `macos-aarch64`
- `windows-x86_64`
- `windows-aarch64`
Prebuilt artifacts are published by the GitHub release workflow when runner
budget is available. The crates.io package below builds `radar` from source and
does not depend on those artifacts.
Set the release tag, detect a currently published platform, and download its
archive:
```bash
TAG=v0.6.0
case "$(uname -s)-$(uname -m)" in
Linux-x86_64) TARGET=linux-x86_64 ;;
Linux-aarch64|Linux-arm64) TARGET=linux-aarch64 ;;
Darwin-x86_64) TARGET=macos-x86_64 ;;
Darwin-arm64) TARGET=macos-aarch64 ;;
*) echo "unsupported release target: $(uname -s)-$(uname -m)" >&2; exit 1 ;;
esac
ASSET="radar-${TAG}-${TARGET}.tar.gz"
BASE="https://github.com/Sanix-Darker/radar/releases/download/${TAG}"
curl -fL -o "$ASSET" "$BASE/$ASSET"
curl -fL -o "$ASSET.sha256" "$BASE/$ASSET.sha256"
```
Verify the checksum:
```bash
if command -v sha256sum >/dev/null 2>&1; then
sha256sum -c "$ASSET.sha256"
else
shasum -a 256 -c "$ASSET.sha256"
fi
```
Extract and install for the current user:
```bash
BUNDLE_DIR=$(mktemp -d)
tar -C "$BUNDLE_DIR" -xzf "$ASSET"
mkdir -p "$HOME/.local/bin"
install -m 0755 "$BUNDLE_DIR/radar" "$HOME/.local/bin/radar"
rm -rf "$BUNDLE_DIR"
export PATH="$HOME/.local/bin:$PATH"
```
Add the PATH export to your shell profile. To install system-wide, place the
binary in `/usr/local/bin` with suitable permissions.
If macOS blocks the checksum-verified binary, remove quarantine from that file:
```bash
xattr -d com.apple.quarantine "$HOME/.local/bin/radar"
```
Smoke test the artifact:
```bash
radar --version
radar --help
```
On Windows PowerShell, select `windows-aarch64` when
`$env:PROCESSOR_ARCHITECTURE` is `ARM64`; otherwise select
`windows-x86_64`. Download and verify the `.zip` archive:
```powershell
$TAG = "v0.6.0"
$TARGET = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "windows-aarch64" } else { "windows-x86_64" }
$ASSET = "radar-$TAG-$TARGET.zip"
$BASE = "https://github.com/Sanix-Darker/radar/releases/download/$TAG"
Invoke-WebRequest "$BASE/$ASSET" -OutFile $ASSET
Invoke-WebRequest "$BASE/$ASSET.sha256" -OutFile "$ASSET.sha256"
$expected = (Get-Content "$ASSET.sha256").Split()[0].ToLowerInvariant()
$actual = (Get-FileHash $ASSET -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "checksum mismatch for $ASSET" }
Expand-Archive $ASSET -DestinationPath radar-release -Force
New-Item -ItemType Directory -Force "$HOME\.local\bin" | Out-Null
Copy-Item radar-release\radar.exe "$HOME\.local\bin\radar.exe" -Force
& "$HOME\.local\bin\radar.exe" --version
```
Each archive also includes `README.md`, `CHANGELOG.md`, `LICENSE.txt`, and
generated man pages. Linux artifacts are static musl binaries and do not
depend on the build runner's glibc version.
## Install from crates.io
The crates.io package is `rdar`; the installed command is `radar`:
```bash
cargo install --locked rdar
radar --version
```
For project-wide automation with Codex and Claude Code, install the skills pack:
```bash
npx skills add Sanix-Darker/radar-skills -a codex -a claude-code
```
Cargo builds the `radar` binary from the published Rust source package.
## Build from source
Rust 1.88 or newer is required:
```bash
git clone https://github.com/Sanix-Darker/radar.git
cd radar
cargo install --locked --path .
radar --version
```
The crate is named `rdar`; the installed command is `radar`.
## Quick start
Run from a repository root:
```bash
radar map
radar check
radar init
radar query "where is token verification handled?"
radar query "in verify_token, how is the signature checked?" --source
```
Useful maintenance commands:
```bash
radar tree
radar refresh
radar refresh --since HEAD~1
radar refresh --deep
radar impact --since HEAD
radar impact --since HEAD --history
radar status
radar watch
```
Verified route cache:
```bash
radar route find "where is token verification handled?"
radar route add "where is token verification handled?" src/auth.rs#verify_token
```
Optional semantic purpose slots:
```bash
radar slots
radar slots --prompt
radar slots --exec "your-agent-command"
radar fill src/MAP.md purpose "Owns scanning, extraction, and map emission."
```
Human-facing views:
```bash
radar browse
radar export --html radar-map.html
radar serve --web 127.0.0.1:8080
```
## Resident MCP server
Native `MAP.md` reads and `radar query` have no standing tool-schema cost. For
hosts that benefit from a persistent process, configure a repository-scoped
stdio server:
```json
{
"mcpServers": {
"radar": {
"command": "/home/me/.local/bin/radar",
"args": ["serve", "--mcp", "/absolute/path/to/repository"]
}
}
}
```
The server exposes one read-only tool:
- `navigate`: resolve a complete task to an exact source anchor, bounded
source candidates, a repository overview, or compact scope metadata.
Call it once with the complete task. Copy a `FINAL SOURCE ANCHOR` exactly.
Open source only when implementation details are needed.
The MCP path is optional. In the latest live consumer gate it used more model
input than the direct command, despite local request processing below 0.11 ms
p95. This is why `radar query` remains the recommended default.
## Design guarantees
- Same source tree produces byte-identical generated content.
- Root, inner, and leaf map bodies are capped at 2,400, 1,600, and 1,200 bytes.
- Exit codes 0, 1, 2, and 3 are stable.
- Cache corruption or version mismatch rebuilds from source.
- Query snapshots are rejected when their canonical state cache changes or
their posting indexes fail validation; MCP frames are bounded at 16 MiB.
- Sixteen parser modes use statically linked tree-sitter grammars.
- The core has at most eight direct runtime dependencies.
- Repository input does not cause library panics.
- Tagged releases provide native x86_64 and ARM64 artifacts for Linux, macOS,
and Windows.
## Development
```bash
make help
make ci
make perf
```
`make ci` runs formatting, clippy with warnings denied, type checks, all Rust
tests, rustdoc with warnings denied, benchmark-harness tests, shell syntax
checks, and cheap benchmark smoke runs. Pull requests and pushes to the primary
branch run the complete gates on Ubuntu and macOS. Native Windows x86_64 and
ARM64 jobs check, test, release-build, execute, package, and checksum their
artifacts. A separate job verifies Rust 1.88, and Linux artifact jobs verify
static x86_64 and arm64 binaries.
Contributors should read [AGENTS.md](AGENTS.md),
[ARCHITECTURE.md](ARCHITECTURE.md), and the
[strategy archive](strategies/README.md). Performance changes require a
defined gate, before and after evidence, and rollback when the evidence fails.
## License
MIT. See [LICENSE.txt](LICENSE.txt).