Give coding agents the repo context they need before they start searching.
Madar builds a local graph of your TypeScript/Node repo, then gives agents like Claude Code, Cursor, Codex, Copilot, Gemini, Aider, and OpenCode a task-aware context pack for the question you are asking.
It helps agents spend less time rediscovering the same files, routes, imports, and flows.
In the latest public TypeScript benchmark receipts, Madar produced proof-backed full_win outcomes on 6/6 explain-runtime legacy rows with strict runtime-proof gates enabled.
On large repos, coding agents often burn context before they can answer:
- broad searches across unrelated folders
- repeated file discovery every session
- wrong-file edits because the first context was too shallow
Madar gives the agent a smaller, repo-grounded starting point.
It does not replace the agent. It helps the agent start from better evidence.
For each task, Madar can surface:
- the likely entry files, symbols, routes, and handlers
- direct snippets and file paths for the current question
- relationships such as imports, calls, framework roles, and runtime handoffs
- freshness metadata tied to git state
- share-safe benchmark and handoff artifacts for review
The goal is not to make the agent blind to the repo. The goal is to make the first pass smaller, more relevant, and easier to verify.
npm install -g @lubab/madarMadar requires Node.js 20 or newer.
Run this inside your repo:
madar try "how does auth work?"That command builds or reuses the local graph, prints a first context-pack result, and suggests the next install command.
For the manual flow:
madar generate .
madar summary
madar doctor
madar statusThen connect an agent:
madar claude installNow ask your agent normal repo questions:
How does auth work?
Where is the report generated?
Add telemetry to this flow.
Why does this endpoint return 403?
The agent can ask Madar for relevant files, symbols, snippets, and relationships before doing raw repo search.
madar claude install
madar codex install
madar cursor install
madar copilot install
madar gemini install
madar aider install
madar opencode installAfter installing a profile, run madar doctor and madar status. Installer details are in the CLI and MCP reference.
You can also generate context directly from the CLI:
madar pack "how does auth work?" --task explain --format textCreate an agent-ready prompt:
madar prompt "how does auth work?" --provider claudeCreate a share-safe handoff for another coding tool:
madar handoff "add auth telemetry" --task implement --consumer copilotMadar analyzes your local repo and creates a graph of files, imports, exports, symbols, routes, handlers, call relationships, dependency relationships, framework metadata, and task-relevant snippets.
The graph is stored locally in your project output folder.
Madar is most useful when:
- your repo is medium or large
- the project is TypeScript or Node.js
- agents keep opening too many files
- you ask architecture, flow, review, or impact questions
- you want more task-aware context before edits
- token usage, latency, or local repo privacy matter
It helps less when:
- the repo is small
- the task is obvious from one file
- the question needs live runtime behavior
- the code relies heavily on dynamic patterns static analysis cannot see
- the generated graph is stale after large repo changes
If the repo changed a lot, regenerate:
madar generate .Madar records graph freshness so agents can tell whether context still matches the repo. On git workspaces, freshness is tied to the graph build commit plus the working-tree diff, so unrelated changes do not have to block a focused task by default.
madar pack "how does auth work?" --require-fresh-context
madar pack "how does auth work?" --require-fresh-graphUse --require-fresh-context when the selected files must be fresh. Use --require-fresh-graph when the whole graph must match the current repo.
Madar now has proof-backed public TypeScript explain-runtime legacy benchmark receipts across six open-source repos. Each row below has benchmark_outcome = "full_win", benchmark_readiness = "ready", answer_quality.madar.passed = true, and answer_contract.runtime_proof.missing_obligations = [].
| Repo | Input tokens | Fresh tokens | Tool calls | Turns | Latency | Cost |
|---|---|---|---|---|---|---|
documenso |
174,504 -> 76,721 (2.27x) | 31,754 -> 16,001 (1.98x) | 7 -> 2 | 8 -> 3 | 58.2s -> 35.3s (1.65x) | $0.3498 -> $0.1634 (2.14x) |
formbricks |
163,482 -> 74,395 (2.20x) | 19,471 -> 14,663 (1.33x) | 37 -> 2 | 6 -> 3 | 157.6s -> 22.6s (6.99x) | $0.4973 -> $0.1350 (3.68x) |
dub |
233,038 -> 76,538 (3.04x) | 33,088 -> 15,847 (2.09x) | 9 -> 2 | 10 -> 3 | 69.4s -> 30.2s (2.29x) | $0.3928 -> $0.1570 (2.50x) |
twenty |
694,972 -> 103,125 (6.74x) | 48,000 -> 22,355 (2.15x) | 21 -> 3 | 22 -> 4 | 128.5s -> 58.7s (2.19x) | $0.8000 -> $0.2069 (3.87x) |
cal-diy |
1,588,241 -> 101,820 (15.60x) | 61,669 -> 21,688 (2.84x) | 37 -> 3 | 38 -> 4 | 252.0s -> 38.7s (6.51x) | $1.4263 -> $0.1946 (7.33x) |
novu |
1,055,389 -> 75,772 (13.93x) | 63,542 -> 15,491 (4.10x) | 23 -> 2 | 24 -> 3 | 220.3s -> 31.1s (7.09x) | $1.1316 -> $0.1620 (6.98x) |
This is not a universal benchmark claim. These are repo/task-specific, single-trial, legacy-row receipts for public TypeScript explain-runtime prompts. SPI arms are tracked separately and are not folded into this 6/6 claim.
The public evidence map tracks what is proven, what is mixed, and what should not be claimed yet: claims and evidence.
Madar runs locally. Generating a graph does not require an API key or a cloud service. Your code does not leave your machine through Madar graph generation.
Your coding agent may still send prompts or selected file context to its own model provider, depending on how that agent is configured.
Treat every local MCP install, hook, or agent profile as part of your local trust boundary. The threat model is documented here: MCP threat model.
Telemetry is disabled unless you explicitly enable it.
madar telemetry status
madar telemetry enable
madar telemetry disable
madar telemetry clear
madar telemetry report
MADAR_ENABLE_TELEMETRY=1 madar generate .It does not record prompt text, answer text, source paths, source content, or repository names. Full controls: docs/telemetry.md.
Current version: 0.28.1.
0.28.1 is a stability hotfix: a retrieve call with semantic/rerank no longer crashes the MCP server when the optional @huggingface/transformers package is missing, a project-local install of that package now enables semantic/rerank under npx-launched or global installs, and the retrieve tool schema only advertises semantic fields when the capability is actually available.
0.28.0 promoted the public benchmark work to a proof-backed stable release: six public TypeScript explain-runtime legacy rows now have checked-in full_win receipts, strict runtime-proof gates, direct-evidence answer checks, scoped benchmark roots, and share-safe reports. It also includes retrieval and extraction improvements for runtime handoffs, source-visible framework flows, and benchmark reproducibility.
Read the full notes in the 0.28.1 changelog.
| Need | Link |
|---|---|
| First run | Getting started |
| Agent setup | Agent quickstarts |
| CLI and MCP tools | CLI and MCP reference |
| Context-pack model | Context packs |
| Claims and limits | Claims and evidence |
| Benchmarks | Benchmark suite |
| Roadmap | Roadmap |
| Changelog | Changelog |
The most useful contributions right now are:
- testing Madar on real TypeScript and Node.js repos
- reporting cases where the context pack misses important files
- improving Windows, WSL, and MCP setup reliability
- adding framework detection for common repo patterns
- improving docs with real setup examples
For active development, open issues or PRs against the next branch.
Before opening a PR, run:
npm test
npm run build
npm run release:verifySee the full contributor graph on GitHub contributors.
Thanks to everyone shaping Madar. The list below is regenerated automatically on every push to main.
mohanagy |
Gunselheli |
qorexdevs |
zhengjynicolas |
jamemackson |
Special thanks to @jamemackson for #54, the first community-contributed feature in Madar.
MIT. Use it, fork it, ship it.