claude-augur-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek Menon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+<img align="right" src="claude-augur.svg" alt="claude-augur-mcp" width="220">
+
+# claude-augur-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **plan reasoning summaries** in [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Surfaces decisions, tradeoffs, and assumptions as scannable abstracts so you can correct Claude's reasoning at a glance.
+
+<br clear="right">
+
+![claude-augur-mcp](demo/demo.gif)
+
+[![npm version](https://img.shields.io/npm/v/claude-augur-mcp.svg)](https://www.npmjs.com/package/claude-augur-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/) [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff)](#) [![GitHub stars](https://img.shields.io/github/stars/Vvkmnn/claude-augur-mcp?style=social)](https://github.com/Vvkmnn/claude-augur-mcp)
+
+---
+
+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, not 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:**
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-555?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxOCAxMCIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj4KICA8IS0tIENsYXdkOiBDbGF1ZGUgQ29kZSBtYXNjb3QgLS0+CiAgPCEtLSBEZWNvZGVkIGZyb206IOKWkOKWm+KWiOKWiOKWiOKWnOKWjCAvIOKWneKWnOKWiOKWiOKWiOKWiOKWiOKWm+KWmCAvIOKWmOKWmCDilp3ilp0gLS0+CiAgPCEtLSBTdWItcGl4ZWxzIGFyZSAxIHdpZGUgeCAyIHRhbGwgdG8gbWF0Y2ggdGVybWluYWwgY2hhciBjZWxsIGFzcGVjdCByYXRpbyAtLT4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIzIiAgeT0iMCIgd2lkdGg9IjEyIiBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIzIiAgeT0iMiIgd2lkdGg9IjIiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSI2IiAgeT0iMiIgd2lkdGg9IjYiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIxMyIgeT0iMiIgd2lkdGg9IjIiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIxIiAgeT0iNCIgd2lkdGg9IjE2IiBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIzIiAgeT0iNiIgd2lkdGg9IjEyIiBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSI0IiAgeT0iOCIgd2lkdGg9IjEiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSI2IiAgeT0iOCIgd2lkdGg9IjEiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIxMSIgeT0iOCIgd2lkdGg9IjEiICBoZWlnaHQ9IjIiLz4KICA8cmVjdCBmaWxsPSIjZDk3NzU3IiB4PSIxMyIgeT0iOCIgd2lkdGg9IjEiICBoZWlnaHQ9IjIiLz4KPC9zdmc+Cg==)](https://claude.ai/code)
+
+**From shell:**
+
+```bash
+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.)
+
+```json
+{
+  "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:
+
+```bash
+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](https://github.com/Vvkmnn/claude-augur-mcp) [reads](https://github.com/Vvkmnn/claude-augur-mcp/tree/main/src) 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](https://adr.github.io/) — structured format for capturing decisions with context and consequences
+- [Y-Statement ADR variant](https://medium.com/olzzio/y-statements-10eb07b5a177) — concise decision format: "In context X, facing Y, we decided Z, accepting C"
+- Roman [Augurs](https://en.wikipedia.org/wiki/Augur) — priests who interpreted signs and patterns to reveal meaning hidden from ordinary observation
+
+## development
+
+```bash
+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](https://modelcontextprotocol.io/specification) standards
+
+Learn from examples:
+
+- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations
+- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices
+- [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) for npm package development
+
+## license
+
+[MIT](LICENSE)
+
+<hr>
+
+<p align="center"><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="340"></a></p>
+
+<p align="center">
+
+_**[Tomb of the Augurs](https://en.wikipedia.org/wiki/Tomb_of_the_Augurs)**, fresco (Tarquinia, ~530 BCE). Claudius — emperor, scholar, and member of the Augural College — wrote [Tyrrenika](https://en.wikipedia.org/wiki/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>

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MCP server for claude-augur-mcp.
+ *
+ * Single tool: augur_explain — extract plan structure,
+ * return template for Claude to fill inline.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * MCP server for claude-augur-mcp.
+ *
+ * Single tool: augur_explain — extract plan structure,
+ * return template for Claude to fill inline.
+ */
+import { createRequire } from 'module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { extractPlanStructure } from './session.js';
+import { renderTemplate, renderSummary } from './render.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+const SERVER_INSTRUCTIONS = `\ud83d\udcd0 Augur \u2014 Plan Reasoning
+
+Surface Claude's reasoning chain as scannable summaries:
+\u2022 augur_explain(plan_path) \u2014 Extract decisions, tradeoffs, assumptions and render as ASCII summary
+
+After writing/editing plan files, call augur_explain to generate a reasoning abstract.
+Insights use \u2605 Insight boxes. Save notable discoveries with augur_save.`;
+const server = new McpServer({ name: 'claude-augur-mcp', version }, { instructions: SERVER_INSTRUCTIONS });
+server.tool('augur_explain', 'Extract plan structure and return a template for inline rendering. Call after writing/editing plan files. Render the filled template INLINE in your response (not in a code block).', {
+    plan_path: z.string().describe('Absolute path to the plan file'),
+}, async ({ plan_path }) => {
+    let planContent;
+    try {
+        planContent = readFileSync(plan_path, 'utf-8');
+    }
+    catch {
+        return { content: [{ type: 'text', text: `Error: Cannot read plan file at ${plan_path}` }] };
+    }
+    const structure = extractPlanStructure(planContent);
+    const summary = renderSummary(structure, plan_path);
+    const template = renderTemplate(structure, plan_path);
+    return {
+        content: [
+            { type: 'text', text: summary },
+            { type: 'text', text: template },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,MAAM,mBAAmB,GAAG;;;;;;6EAMiD,CAAC;AAE9E,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,EACrC,EAAE,YAAY,EAAE,mBAAmB,EAAE,CACtC,CAAC;AAEF,MAAM,CAAC,IAAI,CACT,eAAe,EACf,qLAAqL,EACrL;IACE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;CACjE,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;IACtB,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,mCAAmC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC;IACxG,CAAC;IAED,MAAM,SAAS,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAEtD,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE;YACxC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC1C;KACF,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Template generator for plan abstracts.
+ *
+ * Generates a left-gutter format with section headers and [FILL] markers.
+ * MCP pre-renders header, purpose, and progress.
+ * Claude fills decisions, assumptions, tradeoffs, reasoning inline.
+ */
+import type { PlanStructure } from './types.js';
+export declare function renderTemplate(structure: PlanStructure, planPath: string): string;
+export declare function renderSummary(structure: PlanStructure, planPath: string): string;

package/dist/render.js

@@ -0,0 +1,76 @@
+/**
+ * Template generator for plan abstracts.
+ *
+ * Generates a left-gutter format with section headers and [FILL] markers.
+ * MCP pre-renders header, purpose, and progress.
+ * Claude fills decisions, assumptions, tradeoffs, reasoning inline.
+ */
+const W = 66;
+const CONTENT_W = W - 2; // width after "│ " prefix
+/** Word-wrap text to multiple lines — never truncates, always includes all words */
+function wrap(text, maxWidth) {
+    const words = text.split(' ');
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        const test = current ? current + ' ' + word : word;
+        if (test.length > maxWidth && current) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = test;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines;
+}
+/** Section header: ├ Name ─────────── (exact W width) */
+function sec(name) {
+    const trail = '\u2500'.repeat(Math.max(3, W - name.length - 3));
+    return `\u251c ${name} ${trail}`;
+}
+export function renderTemplate(structure, planPath) {
+    const { project, purpose, doneLine, nextLine, sections } = structure;
+    const file = planPath.split('/').pop() || planPath;
+    // Header: ┌ 📐 project · file trail (never truncated)
+    const label = `${project} \u00b7 ${file}`;
+    const trail = '\u2500'.repeat(Math.max(3, W - label.length - 5));
+    const purposeLines = wrap(purpose, CONTENT_W).map(l => `\u2502 ${l}`).join('\n');
+    const sectionList = sections.slice(0, 6).join(', ');
+    return `Include this abstract in your response (not in a code block). Header and progress are pre-rendered \u2014 fill the remaining sections.
+
+\u250c \ud83d\udcd0 ${label} ${trail}
+${purposeLines}
+\u2502
+${sec('Progress')}
+\u2502 ${doneLine}
+\u2502 ${nextLine}
+\u2502
+${sec('Decisions')}
+\u2502 [FILL: 2-4 decisions, format: "\u2713 choice \u2014 reason"]
+\u2502 [child decisions use: "  \u2514 choice \u2014 reason"]
+\u2502
+${sec('Assumptions')}
+\u2502 [FILL: 1-2 assumptions, format: "? statement"]
+\u2502
+${sec('Tradeoffs')}
+\u2502 [FILL: 1-2 lines, "+" for pro, "\u2212" for con]
+\u2502
+${sec('Reasoning')}
+\u2502 [FILL: 2-3 lines explaining WHY]
+\u2514${'\u2500'.repeat(W)}
+
+Rules:
+- Every content line starts with "\u2502 "
+- ~60 chars max per line after "\u2502 "
+- Terse: verb phrases, no articles, no filler
+- Plan sections: ${sectionList}`;
+}
+export function renderSummary(structure, planPath) {
+    const { doneCount, itemCount } = structure;
+    const file = planPath.split('/').pop() || planPath;
+    return `\ud83d\udcd0 ${file} \u00b7 ${doneCount}/${itemCount} done`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Plan structure extractor.
+ *
+ * Reads plan files and extracts metadata for template generation.
+ * Computes progress lines (Done/Next) from step headings + checkboxes.
+ */
+import type { PlanStructure } from './types.js';
+/**
+ * Extract structured metadata from a plan file.
+ * Reads title, purpose, section headings, checkbox counts, and step progress.
+ */
+export declare function extractPlanStructure(planContent: string): PlanStructure;

package/dist/session.js

@@ -0,0 +1,121 @@
+/**
+ * Plan structure extractor.
+ *
+ * Reads plan files and extracts metadata for template generation.
+ * Computes progress lines (Done/Next) from step headings + checkboxes.
+ */
+/** Truncate text at a word boundary, not mid-word */
+function truncAtWord(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    const cut = text.substring(0, maxLen);
+    const sp = cut.lastIndexOf(' ');
+    return sp > maxLen * 0.4 ? cut.substring(0, sp) : cut;
+}
+/** Extract a short name from a step heading like "### Step 2: Pivot to template approach (from live test)" */
+function extractStepName(heading) {
+    let name = heading.replace(/^###\s+/, '');
+    name = name.replace(/^Step\s+\d+:\s*/i, '');
+    name = name.replace(/\*\*/g, '');
+    // Cut at first delimiter for brevity
+    for (const sep of [' — ', ' - ', ' (', ' + ']) {
+        const idx = name.indexOf(sep);
+        if (idx > 0) {
+            name = name.substring(0, idx);
+            break;
+        }
+    }
+    // Trim trailing punctuation/spaces after word-boundary truncation
+    return truncAtWord(name.trim(), 18).replace(/[\s+\-]+$/, '');
+}
+/**
+ * Extract structured metadata from a plan file.
+ * Reads title, purpose, section headings, checkbox counts, and step progress.
+ */
+export function extractPlanStructure(planContent) {
+    const lines = planContent.split('\n');
+    let title = 'Untitled Plan';
+    let purpose = '';
+    const sections = [];
+    let itemCount = 0;
+    let doneCount = 0;
+    let foundPurpose = false;
+    const steps = [];
+    let currentStep = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('# ') && title === 'Untitled Plan') {
+            title = trimmed.replace(/^#\s+/, '');
+            continue;
+        }
+        if (trimmed.startsWith('## ')) {
+            const section = trimmed.replace(/^##\s+/, '');
+            if (!section.startsWith('Detail:')) {
+                sections.push(truncAtWord(section, 30));
+            }
+        }
+        if (trimmed.match(/^###\s+Step\s+\d/i)) {
+            if (currentStep)
+                steps.push(currentStep);
+            currentStep = { name: extractStepName(trimmed), items: 0, done: 0 };
+        }
+        if (trimmed.startsWith('- [')) {
+            itemCount++;
+            if (currentStep)
+                currentStep.items++;
+            if (trimmed.startsWith('- [x]')) {
+                doneCount++;
+                if (currentStep)
+                    currentStep.done++;
+            }
+        }
+        if (!foundPurpose && trimmed.length > 15) {
+            const goalMatch = trimmed.match(/\*\*(?:Primary goal|How it works)\*\*:\s*(.+)/);
+            if (goalMatch) {
+                purpose = goalMatch[1];
+                foundPurpose = true;
+            }
+            else if (!purpose &&
+                !trimmed.startsWith('#') &&
+                !trimmed.startsWith('**Progress') &&
+                !trimmed.startsWith('-') &&
+                !trimmed.startsWith('|') &&
+                !trimmed.startsWith('```') &&
+                !trimmed.startsWith('---')) {
+                purpose = trimmed;
+            }
+        }
+    }
+    if (currentStep)
+        steps.push(currentStep);
+    // Build progress lines
+    const doneSteps = steps.filter(s => s.items > 0 && s.done === s.items).map(s => s.name);
+    const pendingSteps = steps.filter(s => s.items === 0 || s.done < s.items).map(s => s.name);
+    const doneNames = doneSteps.slice(0, 2).join(', ');
+    const doneExtra = doneSteps.length > 2 ? ` + ${doneSteps.length - 2} more` : '';
+    const doneLine = `Done (${doneCount}/${itemCount}): ${doneNames || 'none yet'}${doneExtra}`;
+    let nextLine;
+    if (pendingSteps.length === 0) {
+        nextLine = 'Next: all done!';
+    }
+    else if (pendingSteps.length === 1) {
+        nextLine = `Next: ${pendingSteps[0]}`;
+    }
+    else {
+        nextLine = `Next: ${pendingSteps[0]} + ${pendingSteps.length - 1} more`;
+    }
+    // Extract project name from title (before ":" if present)
+    const colonIdx = title.indexOf(':');
+    const project = colonIdx > 0 ? title.substring(0, colonIdx).trim() : title;
+    return {
+        title,
+        project,
+        purpose: purpose || 'No description',
+        sections,
+        itemCount,
+        doneCount,
+        doneLine,
+        nextLine,
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JSONL storage for insights and explanations.
+ *
+ * Location: ~/.claude/teacher/
+ *   insights.jsonl — persistent educational insights
+ *   explanations.jsonl — plan reasoning history
+ */
+import type { Insight, InsightDepth, Explanation } from './types.js';
+/**
+ * Save an insight. Deduplicates by topic + content substring match.
+ * Returns the saved insight, or null if it was a duplicate.
+ */
+export declare function saveInsight(insight: string, topic: string, tags?: string[], depth?: InsightDepth, project?: string): Insight | null;
+/**
+ * Search insights by keyword (in insight text) and/or topic filter.
+ */
+export declare function recallInsights(query?: string, topic?: string, limit?: number): Insight[];
+/**
+ * Get topic breakdown with counts for learning progress overview.
+ */
+export declare function reviewInsights(): Record<string, {
+    count: number;
+    depths: Record<string, number>;
+}>;
+/**
+ * Remove an insight by ID. Returns true if found and removed.
+ */
+export declare function forgetInsight(id: string): boolean;
+/**
+ * Save a plan explanation for history.
+ */
+export declare function saveExplanation(planPath: string, title: string): Explanation;

package/dist/storage.js

@@ -0,0 +1,120 @@
+/**
+ * JSONL storage for insights and explanations.
+ *
+ * Location: ~/.claude/teacher/
+ *   insights.jsonl — persistent educational insights
+ *   explanations.jsonl — plan reasoning history
+ */
+import { readFileSync, appendFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+const STORE_DIR = join(homedir(), '.claude/teacher');
+const INSIGHTS_FILE = join(STORE_DIR, 'insights.jsonl');
+const EXPLANATIONS_FILE = join(STORE_DIR, 'explanations.jsonl');
+function ensureDir() {
+    if (!existsSync(STORE_DIR)) {
+        mkdirSync(STORE_DIR, { recursive: true });
+    }
+}
+// ── Insights ────────────────────────────────────────────────────
+function readInsights() {
+    ensureDir();
+    if (!existsSync(INSIGHTS_FILE))
+        return [];
+    try {
+        return readFileSync(INSIGHTS_FILE, 'utf-8')
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Save an insight. Deduplicates by topic + content substring match.
+ * Returns the saved insight, or null if it was a duplicate.
+ */
+export function saveInsight(insight, topic, tags = [], depth = 'intro', project) {
+    ensureDir();
+    const existing = readInsights();
+    // Dedup: same topic + first 30 chars of insight match
+    const prefix = insight.substring(0, 30).toLowerCase();
+    const isDuplicate = existing.some((e) => e.topic === topic && e.insight.substring(0, 30).toLowerCase() === prefix);
+    if (isDuplicate)
+        return null;
+    const entry = {
+        id: randomUUID(),
+        insight,
+        topic,
+        tags,
+        depth,
+        project,
+        created: new Date().toISOString(),
+        recalled: 0,
+    };
+    appendFileSync(INSIGHTS_FILE, JSON.stringify(entry) + '\n');
+    return entry;
+}
+/**
+ * Search insights by keyword (in insight text) and/or topic filter.
+ */
+export function recallInsights(query, topic, limit = 5) {
+    const all = readInsights();
+    let filtered = all;
+    if (topic) {
+        filtered = filtered.filter((i) => i.topic === topic);
+    }
+    if (query) {
+        const q = query.toLowerCase();
+        filtered = filtered.filter((i) => i.insight.toLowerCase().includes(q) || i.tags.some((t) => t.toLowerCase().includes(q)));
+    }
+    // Most recently created first
+    filtered.sort((a, b) => new Date(b.created).getTime() - new Date(a.created).getTime());
+    return filtered.slice(0, limit);
+}
+/**
+ * Get topic breakdown with counts for learning progress overview.
+ */
+export function reviewInsights() {
+    const all = readInsights();
+    const topics = {};
+    for (const i of all) {
+        if (!topics[i.topic]) {
+            topics[i.topic] = { count: 0, depths: {} };
+        }
+        topics[i.topic].count++;
+        topics[i.topic].depths[i.depth] = (topics[i.topic].depths[i.depth] || 0) + 1;
+    }
+    return topics;
+}
+/**
+ * Remove an insight by ID. Returns true if found and removed.
+ */
+export function forgetInsight(id) {
+    const all = readInsights();
+    const filtered = all.filter((i) => i.id !== id);
+    if (filtered.length === all.length)
+        return false;
+    ensureDir();
+    writeFileSync(INSIGHTS_FILE, filtered.map((i) => JSON.stringify(i)).join('\n') + '\n');
+    return true;
+}
+// ── Explanations (plan reasoning history) ───────────────────────
+/**
+ * Save a plan explanation for history.
+ */
+export function saveExplanation(planPath, title) {
+    ensureDir();
+    const entry = {
+        id: randomUUID(),
+        plan_path: planPath,
+        title,
+        created: new Date().toISOString(),
+    };
+    appendFileSync(EXPLANATIONS_FILE, JSON.stringify(entry) + '\n');
+    return entry;
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared types for claude-teacher-mcp.
+ *
+ * Single domain: plan structure extraction for template seeding.
+ */
+export interface PlanStructure {
+    title: string;
+    project: string;
+    purpose: string;
+    sections: string[];
+    itemCount: number;
+    doneCount: number;
+    doneLine: string;
+    nextLine: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for claude-teacher-mcp.
+ *
+ * Single domain: plan structure extraction for template seeding.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "claude-augur-mcp",
+  "version": "0.1.0",
+  "description": "An MCP server that surfaces Claude's reasoning chain as scannable plan abstracts and persists educational insights",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "claude-augur-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run typecheck"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "anthropic",
+    "reasoning",
+    "plan-summary",
+    "insights",
+    "augur",
+    "typescript",
+    "nodejs"
+  ],
+  "author": "Vvkmnn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vvkmnn/claude-augur-mcp.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}