<img align="right" src="claude-augur.svg" alt="claude-augur-mcp" width="220">

claude-augur-mcp

A Model Context Protocol (MCP) server for plan reasoning summaries in Claude Code. Surfaces decisions, tradeoffs, and assumptions as scannable abstracts so you can correct Claude's reasoning at a glance.

<br clear="right">

---

Claude's reasoning about plans is invisible. When Claude writes a plan, its decisions, assumptions, and tradeoffs are buried in the document. You have to read the entire thing to find them. If Claude assumed the wrong approach or made a bad tradeoff, you won't know until implementation is underway and something breaks.

Augur reads the plan structure and returns a template that Claude fills with its actual reasoning, inline in the response rather than hidden in a collapsed tool result. You see decisions, assumptions, and tradeoffs at a glance and can correct them before a single line of code is written.

install

Requirements:

From shell:

claude mcp add claude-augur-mcp -- npx claude-augur-mcp

From inside Claude (restart required):

Add this to our global mcp config: npx claude-augur-mcp

Install this mcp: https://github.com/Vvkmnn/claude-augur-mcp

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "claude-augur-mcp": {
      "command": "npx",
      "args": ["claude-augur-mcp"],
      "env": {}
    }
  }
}

There is no npm install required: no external databases, no indexing, only Node.js built-ins for filesystem access.

However, if npx resolves the wrong package, you can force resolution with:

npm install -g claude-augur-mcp

features

1 tool. Plan structure extraction. Template seeding. Inline rendering.

augur_explain

Read a plan file and return a structured template for Claude to fill with its reasoning. Claude renders the abstract inline in its response, not hidden in a collapsed tool result.

Call after writing or editing a plan file:

augur_explain plan_path="/Users/you/.claude/plans/your-plan.md"

MCP returns two content blocks:

Block 1: one-line summary, visible even when the tool result is collapsed.

your-plan.md · 10/18 done

Block 2: template with pre-rendered header, progress, and [FILL] markers.

┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ [FILL: 2-4 decisions, format: "✓ choice — reason"]
│ [child decisions use: "  └ choice — reason"]
│
├ Assumptions ────────────────────────────────────────────────────
│ [FILL: 1-2 assumptions, format: "? statement"]
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ [FILL: 1-2 lines, "+" for pro, "−" for con]
│
├ Reasoning ──────────────────────────────────────────────────────
│ [FILL: 2-3 lines explaining WHY]
└──────────────────────────────────────────────────────────────────

Claude fills the template inline:

┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ ✓ Express over Fastify — team familiarity, middleware ecosystem
│   └ Passport.js for auth — proven, supports OAuth + JWT
│ ✓ Redis for rate limiting — atomic counters, TTL built-in
│ ✓ ws over Socket.io — lighter, no fallback polling needed
│
├ Assumptions ────────────────────────────────────────────────────
│ ? Single Redis instance sufficient for current scale
│ ? WebSocket clients handle reconnection gracefully
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ + Redis rate limiting: sub-ms response, horizontal scaling
│ − Extra infrastructure dependency to operate
│
├ Reasoning ──────────────────────────────────────────────────────
│ Auth must be production-grade from day one — Passport.js
│ handles OAuth/JWT without custom crypto. Redis rate limiting
│ chosen over in-memory because the API will be multi-process.
│ ws chosen over Socket.io to avoid 200KB bundle overhead.
└──────────────────────────────────────────────────────────────────

What gets extracted from the plan file:

Field	Source	Example
Project name	H1 title before :	my-project
Purpose	First **Primary goal**: line, or first prose paragraph	Full text, word-wrapped
Sections	H2 headings (excluding Detail: sections)	Context, Architecture, ...
Progress	### Step N: headings with - [x] / - [ ] counts	Done (10/18): Auth, Rate limiter
Done steps	Steps where all items are [x]	Capped at 2 names + N more
Next steps	Steps with pending items	First name + N more

methodology

How claude-augur-mcp reads plans:

                    📐 claude-augur-mcp
                    ━━━━━━━━━━━━━━━━━━━

              Claude writes a plan
                augur_explain
                    │
                    ▼
              ┌─────────────────┐
              │  read plan file │  from disk (read-only)
              │  (session.ts)   │
              └────────┬────────┘
                       │
                       ├── title → project name (before ":")
                       ├── purpose → **Primary goal**: or first prose
                       ├── sections → H2 headings
                       └── progress → ### Step N: with [x]/[ ] counts
                       │
              ┌────────▼────────┐
              │ render template │  left-gutter format
              │ (render.ts)     │  [FILL] markers for Claude
              └────────┬────────┘
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
     block 1                   block 2
     summary                   template
     (visible collapsed)       (Claude renders inline)
          │                         │
          ▼                         ▼
     plan.md · 10/18 done      ┌ 📐 project · plan.md ──
                               │ purpose...
                               ├ Progress ────────────
                               │ Done (10/18): Auth + 1
                               ├ Decisions ───────────
                               │ [FILL]
                               ├ Assumptions ─────────
                               │ [FILL]
                               └──────────────────────


     TEMPLATE SEEDING:

     Regex extraction of Claude's thinking blocks produces garbage:
     free-form prose has no structured patterns to match.

     Augur takes a different approach: extract plan structure (the
     deterministic part), seed a template, let Claude fill reasoning
     (the part only Claude knows). Structure from MCP, content from
     Claude. Consistent format, accurate reasoning.

     MCP pre-renders              Claude fills
     ──────────────               ────────────
     header + purpose             decisions
     progress counts              assumptions
     section labels               tradeoffs
     formatting rules             reasoning

Two-block return: MCP tool results get collapsed in Claude Code UI. Block 1 is a one-line summary visible even when collapsed. Block 2 is the full template that Claude renders inline in its response, visible to the user without expanding.

Read-only: augur_explain only reads the plan file. No disk writes, no state, no side effects. Works in plan mode.

Architecture:

claude-augur-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts       # MCP server, 1 tool
│   ├── types.ts       # PlanStructure interface
│   ├── session.ts     # Plan file parser + step progress extractor
│   └── render.ts      # Template generator with left-gutter format
└── demo/
    ├── demo.cast      # asciinema recording
    └── demo.gif       # animated demo

Design principles:

• Template seeding over regex extraction: regex on thinking blocks produced garbage; template seeding lets Claude fill its own reasoning accurately
• Inline over collapsed: tool results get collapsed in Claude Code UI; inline rendering keeps the abstract visible
• Read-only: no disk writes, no state, works in plan mode
• Single tool: augur_explain does one thing well; no CRUD, no storage, no insight management
• Left-gutter format: ┌│├└ vertical bar with no right border; can't misalign, renders cleanly in any terminal width
• Never truncate: purpose and header always render in full; word-wrapped, never cut

Design influences:

• Architecture Decision Records: structured format for capturing decisions with context and consequences
• Y-Statement ADR variant: concise decision format: "In context X, facing Y, we decided Z, accepting C"
• Roman Augurs: priests who interpreted signs and patterns to reveal meaning hidden from ordinary observation

development

git clone https://github.com/Vvkmnn/claude-augur-mcp && cd claude-augur-mcp
npm install && npm run build

Scripts:

Command	Description
npm run build	TypeScript compilation (tsc && chmod +x dist/index.js)
npm run dev	Watch mode (tsc --watch)
npm start	Run MCP server (node dist/index.js)
npm run clean	Remove build artifacts (rm -rf dist)
npm run typecheck	TypeScript validation without emit
npm test	Type-check

Contributing:

• Fork the repository and create feature branches
• Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

• Official MCP servers for reference implementations
• TypeScript SDK for best practices
• Creating Node.js modules for npm package development

license

MIT

<hr>

<a href="https://en.wikipedia.org/wiki/Tomb_of_the_Augurs"><img src="logo/tomb-of-the-augurs.jpg" alt="Tomb of the Augurs" width="100%"></a>

<p align="center">

Tomb of the Augurs, fresco (Tarquinia, ~530 BCE). Claudius, emperor, scholar, and member of the Augural College, wrote Tyrrenika, a lost 20-volume history of Etruscan civilization and their methods of divination. The augurs' role was not to predict the future, but to interpret the signs and reveal whether a proposed course of action had merit.

</p>