Madar

Madar

Retrieve specific source code for your coding agent.

Madar builds a local repository graph for JavaScript and TypeScript function lookup by file and symbol. Agents can inspect returned source and request omitted lines.

Broad context discovery and workflow packs are experimental: they can omit necessary evidence and increase total tokens once follow-up reads are counted. Consistent whole-task accuracy and token savings have not been established. Use direct source reads when they are sufficient.

[npm] [node >=20] [local first] [license MIT]

Try It in 60 Seconds

Install Madar with Node.js 20 or newer. For an experimental discovery preview, run it inside your repository:

npm install -g @lubab/madarcd your-repositorymadar try "how does authentication work?"

madar try builds or reuses the local graph, prints an experimental source preview, and shows an optional agent-install command. It does not modify your source code.

For a concrete example, Madar's included password-reset workspace contains this path:

account-routes.ts  -> PasswordResetService.requestPasswordReset()  -> userRepository.saveResetToken()  -> enqueueResetEmailJob()  -> sendPasswordResetEmail()

This is an example of a partial starting path. The agent must verify the conditions, dependencies, and failure paths needed for its answer.

Connect Your Agent

Choose the agent you use. For Claude Code:

madar claude install --profile strictmadar doctormadar status

The compact strict profile exposes context_pack and context_expand; full also includes them, while core exposes graph-navigation tools. After installing, run madar doctor and madar status.

When the file and function are known, use this MCP request:

{  "prompt": "Read these functions",  "task": "explain",  "targets": [{"file": "lib/util.js", "symbol": "join"}],  "budget": 1500}

Replace the example file and symbol with those in your repository. Targets select function source, not a complete workflow; inspect omissions and returned continuation handles. A direct source read remains appropriate.

Without exact targets, questions such as these use experimental discovery:

How does authentication work?Why does this endpoint return 403?Where is the report generated?What breaks if I change this service?Add telemetry to this flow.

For MCP source lookup and recovery, use strict. Codex and OpenCode install it automatically; Aider installs prompt guidance without an MCP server.

Installer details are in the CLI and MCP reference. Step-by-step setup and smoke tests are in the agent quickstarts.

After upgrading Madar, rerun your agent's install command to refresh its managed profile. Older profiles may lack automatic refresh or Codex's longer startup window.

During automatic reconciliation, graph-backed calls return a retryable response. If continuing with Madar, retry after its suggested delay. Native source investigation remains available.

What Changes for the Agent

context_pack returns source locations, excerpts, omissions, freshness, and advisory coverage. Its compact source_evidence_v2 response has a serialized token budget, including metadata. A small packet does not establish a cheaper or more accurate investigation.

For exact lookup, use up to eight JavaScript or TypeScript targets, each with a workspace-relative file and case-sensitive symbol. Only explain mode is supported. Missing, ambiguous, excluded, or stale owners are refused. Targets select functions, not complete workflows; they do not infer calls.

To inspect a known call instead, add "callee":"scan" to its caller target. Madar checks the full current caller and returns a uniquely bound local implementation. Identifier and static dotted calls are supported; nested-closure calls and dynamic expressions are excluded. Unverified bindings are refused.

One oversized exact function request returns a budgeted first page; continuations retrieve remaining lines without repetition.

For omitted evidence:

• Follow a node's source_expand_handle with context_expand in the same MCP session. Continue with each returned handle until the remaining whole source lines are delivered. Changed or newly excluded source invalidates the handle.
• Use an expandable handle for related evidence. An optional exact symbol selects a verified function inside that handle's scope. Do not pass a symbol with a source-continuation handle.
• If a page reports budget_insufficient, retry with a larger budget or request fewer targets. Minimum budget: 128 tokens; expansion defaults to 1500.

A snippet_ref points to shared source text; use the referring node's snippet_line_range for its excerpt. When line_number is omitted, use that range's start. Response paths may be workspace-relative.

Experimental discovery can include source-resolved dependencies and static graph relationships. source_dependencies reports verified calls and unresolved locations; selection_omitted reports exact matches omitted by the lookup limit. Unresolved details may use either a flat list or grouped calls, including repeated line_numbers. Counts can exceed the bounded examples shown. None of these establishes runtime execution or whole-task completeness.

Regenerate older graphs to include newly supported source forms. Root/workspace package.json objects up to 128 KiB and JavaScript/TypeScript files under lib/ are eligible under source policy. Exclude generated output with .madarignore. Other JSON configuration files are not source evidence.

How It Works

1. Madar indexes source files, declarations, imports, calls, framework metadata, and selected documentation locally.
2. Exact targets or experimental query matching select source evidence.
3. Responses expose omissions and recovery handles. Installed MCP profiles refresh the graph after workspace changes.

The MCP response shape describes the response contract.

Use Madar Without MCP

The CLI can generate and inspect context without installing an agent integration:

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

By default, madar generate . combines SPI metadata with proven legacy semantics for JavaScript/TypeScript, and uses legacy fallback for other supported languages. Strict modes are in the CLI reference.

Legacy updates rebuild the current corpus when files change or disappear, refreshing incoming calls and imports from unchanged files. Parser caches can still be reused; unchanged graphs are reused after any required extractor-version upgrade.

Create a provider-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

See the getting-started tutorial for a sample workspace.

Where Madar Fits

Consider precise source lookup when you know the JavaScript or TypeScript file and function and need selected bodies with explicit omissions and continuations.

It helps less when the repository is small, one direct read is sufficient, source is stale, or the question depends on dynamic or live runtime behavior. Architecture, review, and impact discovery remain experimental.

Madar complements agents and IDE indexing. It is not a hosted knowledge base, runtime tracer, PR reviewer, or vulnerability scanner.

Local by Design

• Privacy: Madar graph generation runs locally and does not require an API key. Your coding agent may still send prompts or selected file context to its own model provider, depending on that agent's configuration.
• Sensitive files: ordinary security source code remains indexable, while private keys, .env*, credential stores, and known non-source secret material are excluded. This is a path policy, not a content-level secret scanner.
• Freshness: installed MCP profiles use automatic refresh. Manual CLI users can regenerate with madar generate .; strict workflows can require --require-fresh-context or --require-fresh-graph.
• Worktrees: run Madar and the agent from the same linked Git worktree. Each worktree receives isolated graph artifacts outside the checkout; reconnect the MCP server after switching worktrees.
• Telemetry: Telemetry is disabled unless you explicitly enable it. Controls and the exact source-safe event schema are documented in telemetry.

Treat every local MCP install, hook, or agent profile as part of your local trust boundary. Read the MCP threat model.

Evidence and Limits

Madar publishes the prompts, answers, traces, and share-safe reports behind its benchmark statements. Two public experiment types answer different questions and should not be compared as if they were the same test.

Controlled v0.30 evidence

Six June TypeScript runtime-flow trials used a source checkout with task-specific proof profiles. In those controlled runs, Madar was invoked once per row and the recorded results showed:

• 3.5x to 18.5x fewer tool calls
• 2.2x to 15.6x less provider-reported input
• 1.65x to 7.09x lower latency

Those receipts are real measurements of profile-assisted Madar. They demonstrate what the workflow can achieve when the correct task evidence is available. They are not evidence that an untuned npm installation will reproduce the same result for arbitrary questions, because the old prompts and checkout retrieval contained benchmark-specific obligations unavailable to normal package users.

v0.31 production-artifact validation

The July reruns removed that assistance and used the same isolated, unpacked @lubab/[email protected] package artifact. Four of six repositories recorded an agent-adoption failure: no attributable Madar MCP call occurred. The other two invoked Madar but failed strict prompt or answer gates. The correct result is zero valid performance comparisons, not six product losses. These reruns expose adoption and answer-completeness work; they neither confirm nor refute the earlier controlled efficiency measurements.

Read the benchmark suite and all dated receipts or the shorter claims and evidence map.

Current Release

Current version: 0.33.0.

See the 0.33.0 changelog.

Documentation

Contributing

The most useful contributions right now are tests on real TypeScript and Node.js repositories, missed-context reports, Windows/WSL/MCP reliability improvements, framework detection, and clearer setup examples.

Open issues or pull requests against the maintained default branch. Before opening a PR, run:

npm testnpm run buildnpm run release:verify

See the full contributor graph on GitHub contributors.

Contributors

Thanks to everyone shaping Madar. The list below is regenerated automatically on every push to main.

Special thanks to @jamemackson for #54, the first community-contributed feature in Madar.

License

MIT. Use it, fork it, ship it.