madar

# Madar

**Give your coding agent the repo context it needs before it starts searching.**

Madar builds a local graph of your TypeScript or Node.js repository and turns the current question into a small, task-aware context pack. Claude Code, Codex, Cursor, Copilot, Gemini, Aider, and OpenCode can start from relevant files, symbols, snippets, and relationships instead of rediscovering the repository from scratch.

- **Start smaller:** give the agent likely entrypoints and runtime paths before broad search.
- **Stay local:** graph generation does not upload your source code or require a cloud service.
- **Stay current:** installed MCP profiles refresh the graph as the active workspace changes.

[![npm](https://img.shields.io/npm/v/%40lubab%2Fmadar)](https://www.npmjs.com/package/@lubab/madar)
[![node >=20](https://img.shields.io/badge/node-%E2%89%A520-3c873a)](https://nodejs.org/)
[![local first](https://img.shields.io/badge/local--first-no%20cloud%20required-0f766e)](#local-by-design)
[![license MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/mohanagy/madar/blob/main/LICENSE)

## Try It in 60 Seconds

Install Madar with Node.js 20 or newer, then run it inside your repository:

```bash
npm install -g @lubab/madar
cd your-repository
madar try "how does authentication work?"
```

`madar try` builds or reuses the local graph, prints a human-readable first result, and recommends the next agent-install command. It does not modify your source code.

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

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

That is the kind of focused starting path Madar gives an agent before it decides whether any additional file inspection is necessary.

## Connect Your Agent

Choose the agent you use. For Claude Code:

```bash
madar claude install
madar doctor
madar status
```

After installing a profile, run `madar doctor` and `madar status`. The agent can then ask Madar for context when you use normal prompts such as:

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

Madar supports these project-local installers:

| Agent | Install command |
| --- | --- |
| Claude Code | `madar claude install` |
| Codex CLI | `madar codex install` |
| Cursor | `madar cursor install` |
| GitHub Copilot | `madar copilot install` |
| Gemini CLI | `madar gemini install` |
| Aider | `madar aider install` |
| OpenCode | `madar opencode install` |

Installer details are in the [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md). Step-by-step setup and smoke tests are in the [agent quickstarts](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md).

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.

Codex installs create a workspace-scoped MCP block with longer startup and tool timeouts. Madar stays available during initial reconciliation; graph-backed calls become available once the graph is ready.

Starting with `0.31.3`, a graph-backed call made while Madar is `starting`, `pending`, or `reconciling` returns a structured retryable response. The agent should retry the same Madar request after the suggested delay instead of bypassing Madar or running generation manually. A dead refresh owner is recovered automatically; only failed, incomplete, or policy-mismatched graph states ask for repair.

## What Changes for the Agent

Without Madar, a coding agent often begins with broad filename searches, repeated reads, and guesses about which route, service, or handler owns the task.

With Madar, the first pass can include:

- likely files, exported symbols, routes, and handlers
- direct snippets relevant to the question
- imports, calls, framework roles, and runtime handoffs
- a static runtime-path hypothesis when the graph supports one, not a live execution trace
- graph freshness and indexing-completeness signals
- explicit guidance to answer, answer with a caveat, or verify a focused target

Madar does not replace your agent or prevent it from reading code. It gives the agent a smaller, repo-grounded place to start.

## How It Works

```text
Your repository
      |
      v
Local Madar graph
      |
      v
Context for the current question
      |
      v
Claude, Codex, Cursor, or another coding agent
```

1. Madar indexes source files, symbols, imports, calls, routes, handlers, framework metadata, and selected documentation.
2. A question selects a bounded context pack rather than dumping the whole repository into the prompt.
3. The response reports evidence strength, coverage, freshness, and whether focused verification is still needed.
4. Installed MCP profiles watch the active workspace and refresh graph-backed context after relevant changes.

The full response contract, including bounded recovery and answerability states, is documented in [MCP response shape](https://github.com/mohanagy/madar/blob/main/docs/mcp-response-shape.md).

## Use Madar Without MCP

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

```bash
madar generate .
madar summary
madar 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](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md).

Create a provider-ready prompt:

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

Create a share-safe handoff for another coding tool:

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

Generated graphs and indexing manifests stay in the project output location. See the [getting-started tutorial](https://github.com/mohanagy/madar/blob/main/docs/tutorials/getting-started.md) for a reproducible sample workspace and expected output.

## Where Madar Fits

Madar is most useful when:

- your repository is medium or large
- the project is primarily TypeScript or Node.js
- agents keep reopening the same files or searching unrelated folders
- you ask architecture, runtime-flow, review, or impact questions
- token usage, latency, or local repo privacy matter

It helps less when:

- the repository is small or the task is obvious from one file
- the question depends on live runtime behavior that static analysis cannot observe
- the code relies heavily on dynamic patterns that are absent from the graph
- the graph is stale or relevant source files could not be indexed

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](https://github.com/mohanagy/madar/blob/main/docs/telemetry.md).

Treat every local MCP install, hook, or agent profile as part of your local trust boundary. The [MCP threat model](https://github.com/mohanagy/madar/blob/main/docs/security/mcp-threat-model.md) documents the boundary in detail.

## 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/madar@0.31.0` 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](https://github.com/mohanagy/