md-feedback

Review markdown plans before AI agents build. Annotate, gate-check, apply fixes, session handoffs.
★ 4NOASSERTIONdatabases
Install

Config snippet generator goes here (5 client tabs)
README

# MD Feedback

> Review your plan. Guide your AI agent. Ship with confidence.

[English](README.md) | [한국어](README.ko.md)

[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/yeominux.md-feedback-vscode?label=VS%20Code&logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode) [![npm](https://img.shields.io/npm/v/md-feedback?logo=npm)](https://www.npmjs.com/package/md-feedback) [![License: SUL-1.0](https://img.shields.io/badge/License-SUL--1.0-blue.svg)](./LICENSE) [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/ymnseon8)

**MD Feedback** is a VS Code extension and MCP server for reviewing markdown plans before AI agents implement them. Annotate plans with Fix, Question, and Highlight — AI agents read your structured feedback directly through MCP. No copy-paste, no export step, no context lost between sessions.

Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode), open a `.md` plan, select text, press `1/2/3`, and your agent can act on that review immediately.

**You review. The agent builds. Gates track completion. Handoffs preserve context.**

![MD Feedback Demo: annotating a markdown plan with Fix, Question, and Highlight in the VS Code sidebar, then reviewing AI-applied changes](https://raw.githubusercontent.com/yeominux/md-feedback/main/assets/demo.gif)

> Latest (v1.5.7): Web UI for `npx md-feedback` — open your markdown workspace in any browser.

## How It Works

From plan to implementation, the complete AI coding loop:

```plaintext
Step 1  YOU        Write a plan in markdown
          │
Step 2  YOU        Open in MD Feedback sidebar → highlight, fix, question
          │         (press 1, 2, or 3)
          │
Step 3  AGENT      Reads annotations via MCP — no export step needed
          │
Step 4  AGENT      Implements fixes, answers questions
          │
Step 5  YOU        Review AI work → Approve, Request Changes, or Reject
          │
Step 6  AGENT      Gates auto-evaluate
          │         "3 fixes remaining" → "All done, ready to merge"
          │
Step 7  AGENT      Generates handoff → next session picks up where you left off
```

You do steps 1–2 and 5. The agent does the rest.

This is the MCP-first path. If you use export-based workflow, run export after step 2.

## Features

- **3 annotation types**: Highlight (reading mark), Fix (needs change), Question (needs clarification)
- **27 MCP tools** for direct agent integration
- **Export to 11 AI tools**: Claude Code, Cursor, Copilot, Codex, Cline, Windsurf, Roo Code, Gemini, Antigravity, Generic, Handoff
- **Quality gates** with automatic pass/fail evaluation
- **Session handoffs** preserve context across AI agent sessions
- **Checkpoints** track review progress with snapshots
- **Plan cursor** tracks current position in a document
- **Keyboard shortcuts**: press 1, 2, 3 for instant annotation
- **AI applies fixes** via MCP — agent reports implementations, you see inline before/after diffs
- **7 status badges**: Open, Working, Review, Answered, Done, Failed, Won't Fix
- **Rollback**: agent can undo its last change if something went wrong
- **Batch operations**: multiple fixes applied in one transaction
- **Safe text replacement**: when the same text appears multiple times, agents must specify which one to change (prevents accidental wrong-line edits)
- **File safety**: blocks writes to .env, credentials, node_modules
- **Approve / Reject buttons** — accept or dismiss annotations inline, always visible when review needed
- **CodeLens in editor** — approve or reject directly in the markdown file, no sidebar needed
- **Activity Bar badge** — see pending review count at a glance
- **Status bar + toast notifications** — never miss when AI delivers work for review
- **Keyboard shortcuts** — Ctrl+Shift+A to approve, Ctrl+Shift+X to reject
- **Gate override** — manually control gate status when auto-evaluation isn't enough
- **External file diffs inline** — see exactly what AI will change before applying
- **Gate transition notifications** — know when gates unblock or complete
- **Concurrent safety** — prevents data corruption when multiple AI operations run at the same time
- **Auto-refresh**: document updates in real-time when AI writes changes
- **Portable format**: annotations stored as HTML comments — works in any markdown renderer, survives git
- **Rich rendering**: Mermaid diagrams, callout blocks, syntax-highlighted code

## Quick Start (under 2 minutes)

1. **Install** from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode)
2. **Annotate first** — select text in a markdown file, then press `1` (highlight), `2` (fix), `3` (question)
3. **Optional: Connect MCP** — after first annota