madar

Madar is a local, task-aware context-pack compiler for AI coding agents.

A structural graph tells the agent what exists in your codebase. Madar tells the agent what runs for this task: usually a much smaller execution slice or structural subset. It then returns a compact pack with inline snippets so the agent can answer from evidence before it starts searching the repo by hand.

Madar is deterministic local context compilation. It complements agents and IDE indexing; it is not another generic codebase index.

Primary ICP: teams using AI coding agents on medium-to-large TypeScript/Node repos where broad exploration creates cost, latency, privacy, or wrong-file-edit risk.

Not the primary ICP today: tiny repos, throwaway scripts, hosted-dashboard-first buyers, or teams that need broad cross-language parity before the TypeScript/Node proof deepens.

Quickstart

Start with the generated graph. madar generate creates the local graph artifact; madar summary, madar pack, madar prompt, and madar handoff can use that graph without any agent install. Run madar <agent> install only when you want Madar wired into an agent through MCP or local instruction files.

npm install -g @lubab/madar

cd your-project
madar generate .          # builds out/graph.json, no API key, no cloud
madar summary             # bounded repo overview before deeper retrieval
madar claude install      # wires Claude Code to use Madar via MCP
madar doctor              # checks graph freshness + agent/MCP wiring
madar status              # compact readiness summary + next commands

# Optional framework-aware metadata + disk cache:
madar generate . --spi

Now ask your agent something about the codebase. It can start with one bounded retrieve or context_pack call, get labeled snippets with file paths and community context, and then decide whether focused follow-up reads are still needed.

Want a tiny reproducible workspace? Start with examples/sample-workspace/ and the sample workspace tutorial.

Want the broader first-run walkthrough with install verification, one pack, and a safe compare smoke check? Use the getting started tutorial.

Choose your agent

Pick one install target, then rerun madar doctor and madar status so the first result is verified before you ask a broader question:

• Claude Code: madar claude install
• Codex CLI: madar codex install
• Cursor: madar cursor install
• GitHub Copilot CLI: madar copilot install
• Gemini CLI: madar gemini install
• Aider: madar aider install
• OpenCode: madar opencode install

After you generate out/graph.json, madar doctor and madar status check the local install wiring for Claude Code, Cursor, Gemini CLI, and GitHub Copilot CLI. They also lint the AGENTS-based Madar instruction profiles for Codex CLI, OpenCode, and Aider; if a profile drifts, they mark the agent as partial and suggest the matching reinstall command.

Install details, generated files, profiles, and uninstall behavior live in the CLI and MCP reference and compatibility guide.

Without MCP, compile a prompt or pack directly:

madar summary
madar pack "how does auth work?" --task explain --format text
madar pack "add auth telemetry" --task implement --format json
madar handoff "add auth telemetry" --task implement --consumer copilot
madar prompt "how does auth work?" --provider claude

madar prompt stays local. madar pack stays the richer local/full-context surface. madar handoff is the share-safe remote/background-agent artifact for cloud or async workers. Note: compare and benchmark flows can spend paid model tokens when you point them at a real model CLI.

The MCP equivalents include context_pack, context_prompt, and follow-up expansion through stable session refs. For follow-ups, reuse the same session_id with context_prompt when a conversation continues; session_diagnostics tells you whether the turn reused, added, updated, or invalidated prior context. Expect the biggest reuse gains with a mostly stable retrieved graph context. First turns and heavily changed retrieved context naturally show little or no reuse.

Optional semantic retrieval/rerank support is local too, but requires the model package:

npm install @huggingface/transformers

Telemetry

Telemetry is disabled unless you explicitly enable it.

madar telemetry status
madar telemetry enable
madar telemetry disable

MADAR_ENABLE_TELEMETRY=1 madar generate .

The current telemetry model is local-first and source-safe. It records coarse success events for install, generate, pack, and compare, plus version, OS, optional install target, and optional repo-size bucket. It does not record prompt text, answer text, source paths, or source content. Full controls: docs/telemetry.md.

What's New

See the 0.27.8 changelog entry for the full release notes.

Recent highlights:

• 0.27.8 refactors the README into a shorter npm-facing landing page and moves long-form Pack Schema, context-pack, MCP, installer, command, and discovery-rule details into dedicated docs.
• 0.27.7 added the checked-in federation flagship proof: a reproducible frontend/backend/shared fixture plus a synthetic federation receipt.
• Roadmap docs now cover design-partner workflow loops, plugin distribution channels, and language-expansion decisions.
• The larger What's new in 0.23.0 additions remain central: madar summary, the core MCP graph_summary tool, runtime execution_slice output, share-safe report.share-safe.json compare artifacts, and compare --baseline-mode pack_only.
• Public proof workflows are organized under docs/proof-workflows.md, docs/claims-and-evidence.md, and docs/benchmarks/suite/.

When To Use --spi

--spi is still opt-in in 0.27.8. Use it when your repo is framework-heavy TypeScript/JavaScript and you want extra framework-shaped metadata plus disk cache behavior.

It is usually worth it for NestJS, Next.js App Router, Prisma, tRPC, Hono, Fastify, and similar repos where users ask storage-oriented prompts, client/server boundary questions, or request-flow questions. The default pipeline is still fine for simpler repos, non-JS/TS workspaces, or first runs where you do not need the extra framework detail yet.

More detail: context packs and task evidence.

Core Surfaces

Madar builds a local graph once, then compiles task-specific evidence from it:

your prompt
  -> workspace graph
    -> relevant nodes + edges + snippets
      -> compact context pack
        -> AI coding agent

The output surfaces are deliberately small:

• madar summary: bounded repo overview.
• madar pack: task-aware local context pack. JSON mode emits Pack Schema v1.
• madar prompt: provider-ready prompt payload.
• madar handoff: share-safe remote/background-agent artifact.
• pr_impact and review-compare: diff-aware review evidence.
• execution_slice: static runtime-path hypothesis, not a live trace. Its phase_coverage is also static and prompt-scoped; broad report-generation prompts can surface planner/research/report-builder/scoring/renderer/persistence phases without implying live instrumentation.

Runtime-generation prompts stay compact: pack shaping follows the strongest backend path first and suppresses sibling-route noise plus shared-hub fan-out on broad runtime-generation questions.

These seven MCP tools ship in the default core profile: retrieve, pr_impact, impact, call_chain, community_overview, graph_stats, and graph_summary. The full surface is 26 tools, opt-in via MADAR_TOOL_PROFILE=full or --profile full, including context_expand and get_neighbors.

Full command and MCP reference: docs/reference/cli-and-mcp.md.

Evidence And Limits

The current headline proof is one verified GoValidate backend service cell for the prompt "How idea report is being generated":

This is one cell: one prompt, one repo, one agent runtime, one verified install path. Your results will vary by repo shape, prompt type, agent runtime, and other installed tools. Published benchmark cells run in isolation mode. Your local numbers may differ if your Claude Code config differs.

Current evidence also includes a public benchmark suite with per-repo spread, initial fixture-proxy implement/review/impact rows, and workflow-outcome receipts. There is still no single-number cross-repo headline. Mixed evidence and counterexamples are tracked openly, including docs/benchmarks/2026-05-25-founder-command-center-auth-flow/.

Madar is a context/evidence layer for review and security workflows, not a PR reviewer or vulnerability scanner. CodeRabbit, Qodo, Codex Security, and similar tools still decide findings, policy, and remediation behavior. Madar supplies bounded local evidence through pr_impact, review-compare, madar handoff, and report.share-safe.json.

Read the public claim map before using numbers in customer-facing copy: docs/claims-and-evidence.md.

Trust + Limitations

Everything stays local by default. No cloud upload, no API key required. Your code never crosses an HTTP boundary unless you explicitly invoke a model or remote system you configured yourself.

• Build: tree-sitter AST extraction and Louvain community detection, CPU-local.
• Query: BM25 lexical scoring, reciprocal-rank fusion, optional ONNX embeddings, and optional cross-encoder reranker.
• MCP: local stdio subprocess of your agent.
• Security boundary: local-first is not automatically safe. Treat every Madar MCP install, plugin, hook, or AGENTS profile as a local trust boundary. Only enable it for repositories and local agent runtimes you trust. Prefer --profile strict when you only need the lean core MCP tools. Threat model: docs/security/mcp-threat-model.md.

Limitations to know:

1. Cold-start sessions add a one-time MCP/tool-schema cost. Core profile is about ~3,200 bytes / ~800 tokens, down about 25% from the original surface.
2. Deep extraction is still best on JS/TS. Python has conservative cross-file import/call resolution, FastAPI router composition, and first-pass Django URL-conf route-to-view mapping. Go has conservative local-package import, receiver-call, and net/http / Gin / Chi route support. Python and Go are still not near JS/TS parity.
3. Static analysis cannot resolve every dynamic runtime behavior.
4. Token reduction depends on project and task.
5. Some workflows still need full file reads, tests, and review.

Documentation

Contributors

Thanks to everyone shaping madar. The list below is regenerated automatically on every push to main by .github/workflows/contributors.yml.

mohanagy

Gunselheli

qorexdevs

zhengjynicolas

jamemackson

A specific shout-out to @jamemackson for #54, adding OpenCode MCP installer support, the first community-contributed feature in madar.

License

MIT. Use it, fork it, ship it.