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.
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.
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.
On one verified GoValidate backend explain task, Madar reduced:
| Metric | Without Madar | With Madar |
|---|---|---|
| Tool calls | 28 | 7 |
| Input tokens | 2,366,946 | 498,688 |
| Wall-clock latency | 158,995 ms | 72,420 ms |
| Cost | $2.6595 | $0.9728 |
This is not a universal benchmark claim. It is one repo, one prompt, one agent runtime, and one verified install path.
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.27.9.
This release includes the stable next-track adoption bundle: the one-command madar try flow, opt-in telemetry, verified agent quickstarts, public benchmark-suite work, freshness improvements, and Windows Claude workflow fixes.
Read the full notes in the 0.27.9 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.