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 for the latest reproducible measurements, OPTIMIZATIONS.md for every accepted or rejected proposal, and ARCHITECTURE.md for the implementation contract.

The public product page is radar.sanixdk.xyz. Its dependency-free source and generic Caddy deployment example live in 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.

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.

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 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, not a rival's headline token percentage.

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 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.

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:

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:

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:

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:

xattr -d com.apple.quarantine "$HOME/.local/bin/radar"

Smoke test the artifact:

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:

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

cargo install --locked rdar
radar --version

For project-wide automation with Codex and Claude Code, install the skills pack:

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:

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:

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:

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:

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:

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:

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:

{
  "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

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, ARCHITECTURE.md, and the strategy archive. Performance changes require a defined gate, before and after evidence, and rollback when the evidence fails.

License

MIT. See LICENSE.txt.