Madar

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.

Why

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.

What Agents Get

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.

Supported Agents

madar claude install
madar codex install
madar cursor install
madar copilot install
madar gemini install
madar aider install
madar opencode install

After installing a profile, run madar doctor and madar status. Installer details are in the CLI and MCP reference.

Use Without MCP

You can also generate context directly from the CLI:

madar pack "how does auth work?" --task explain --format text

Create an agent-ready prompt:

madar prompt "how does auth work?" --provider claude

Create a share-safe handoff for another coding tool:

madar handoff "add auth telemetry" --task implement --consumer copilot

What It Builds

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

Fit

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 .

Freshness

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

Use --require-fresh-context when the selected files must be fresh. Use --require-fresh-graph when the whole graph must match the current repo.

Evidence

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 = [].

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.

Privacy

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

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.

What's New

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.

Docs

Install

npm install -g @lubab/madar

Madar requires Node.js 20 or newer.

Quick Start

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 status

Then connect an agent:

madar claude install

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

License

MIT. Use it, fork it, ship it.