pi-mdiff

Markdown has a granularity problem that code doesn't. In code, a line is a unit of meaning. In markdown, a paragraph is — but it can span 1 line or 10 depending on who last ran the formatter. pi-mdiff fixes this for the pi coding agent.

The problem

Pi's normal edit tool uses exact text matching. That is brittle for Markdown because prose is semantically paragraph-based, but physically line-wrapped by whatever formatter, editor, or human last touched the file.

A paragraph like this:

The system uses PostgreSQL for all storage.
The schema is defined in schema.sql.
All queries go through the repository layer.

…is identical in meaning to this:

The system uses PostgreSQL for all storage. The schema is defined in schema.sql. All queries go through the repository layer.

A formatter rewraps it. The content is equivalent, but an exact SEARCH block no longer matches the physical lines in the file. The agent sees a tool error even though it identified the right paragraph.

Error: cannot find matching context in docs/architecture.md
<<<<<<< SEARCH
The system uses PostgreSQL for all storage.
The schema is defined in schema.sql.
All queries go through the repository layer.

pi-mdiff fixes the agent workflow around Markdown: normal edit calls get soft-wrap-aware matching, and larger prose changes can use section/block anchors instead of fragile exact text.

Install

pi install npm:@trycedar/pi-mdiff

No config, no API keys.

Try this first

After installing, ask pi naturally:

Update the Architecture section of docs/README.md to mention that we moved to PostgreSQL.

Inspect docs/CONTRIBUTING.md and rewrite the Getting Started section.

Delete the "Legacy Notes" section from docs/api.md.

Add a new "Troubleshooting" section after Installation in README.md.

pi will use md_inspect to find the right section and md_edit to apply the change — no fragile text matching involved.

What this adds

Transparent fix for edit on .md files

Every edit call on a markdown file is intercepted. SEARCH blocks are normalized to paragraph granularity before matching — soft-wrapped lines joined, blank lines collapsed, bullets standardized. Fenced code and frontmatter are never touched.

Before pi-mdiff: formatter reflows paragraph → SEARCH fails → LLM retries → confusion.

After pi-mdiff: normalization runs silently → match found → edit applied → done.

If the built-in edit still cannot match, pi-mdiff attempts normalized soft-wrap recovery and returns success only when it can apply the intended edit.

md_inspect — see section structure before editing

md_inspect path="docs/architecture.md"

## Overview  (path: Overview, lines 1-6)
  [0] paragraph lines 3-4: "This project is a web application that helps…"
## Database Layer  (path: Database Layer, lines 7-13)
  [0] paragraph lines 9-10: "We use PostgreSQL for all persistent storage…"
  [1] paragraph lines 12-13: "Migrations are managed via Alembic…"
## API Layer  (path: API Layer, lines 14-18)
  [0] paragraph lines 16-18: "The REST API is built with Express…"

Shows every section heading, heading path, line range, and block inside it, with 0-based block indices. Call this before md_edit so you know exactly what to target. Heading paths disambiguate repeated section names such as API > Usage and CLI > Usage.

md_edit — section-anchored editing

md_edit path="docs/architecture.md"
        operation="replace"
        section="## Database Layer"
        block_index=0
        content="We use PostgreSQL for all persistent storage.
The schema is defined in schema.sql and managed via Alembic."

Anchors to a heading + block index. No text matching at all. Formatters can reflow the entire file — this still works.

| Operation | What it does | |---|---| | replace | Replace the block at block_index with new content | | insert_after | Insert a new block after block_index | | delete | Remove the block at block_index | | append | Add a new block at the end of the section | | rename_section | Rename the section heading itself | | delete_section | Remove the entire section including its heading | | add_section | Insert a brand-new section after another; content includes the heading line |

md_diff — review Markdown structurally

md_diff before_path="/tmp/architecture.before.md"
        after_path="docs/architecture.md"

Reports changes by heading path and block index instead of raw physical lines:

~ section Database Layer
  ~ [0] paragraph lines 9-10 → 9-11
    - "We use SQLite for local storage…"
    + "We use PostgreSQL for persistent storage…"

Use this when a normal line diff is noisy because prose was reflowed. It helps the agent verify what changed at the Markdown block level.

Common workflows

| Task | How to ask | |---|---| | Update a specific section | "Rewrite the Deployment section of docs/README.md to mention Docker." | | Add content to a section | "Add a note about rate limiting at the end of the Authentication section." | | Add a new section | "Add a Troubleshooting section after Installation in README.md." | | Rename a section | "Rename the 'Legacy API' section to 'Deprecated API' in docs/api.md." | | Delete stale content | "Remove the 'Legacy API' section from docs/api.md." | | Bulk doc update | "Update all references to 'SQLite' to 'PostgreSQL' in docs/architecture.md." | | Inspect before editing | "Show me the structure of CONTRIBUTING.md before we edit it." |

What the normalizer preserves

Only prose lines are joined. Everything structurally meaningful is left exactly as-is:

| Element | Example | Touched? | |---|---|---| | Fenced code blocks | ```…``` | Never | | YAML frontmatter | ---\ntitle: …\n--- | Never | | Table rows | \| Col A \| Col B \| | Never | | Headings | ## Section Name | Never | | List items | - item, - nested | Never | | Blockquotes | > quoted text | Never | | Horizontal rules | ---, *** | Never | | Explicit line breaks | line ending with | Never | | Inline code | `code` | Never |

Tools

md_inspect

| Parameter | Description | |---|---| | path | Path to the markdown file (.md or .markdown) |

Returns a formatted section map with heading paths, section line ranges, block line ranges, block type, and preview text. Use before md_edit to find the right section and block_index.

md_edit

| Parameter | Description | |---|---| | path | Path to the markdown file (.md or .markdown) | | operation | See table above | | section | Heading text to anchor to — case-insensitive, ## prefix optional. For add_section: the section to insert after (use (end) to append at end of file) | | block_index | 0-based index of the target block (not needed for append, rename_section, delete_section, add_section) | | content | New content — required for replace, insert_after, append, add_section; new heading text for rename_section |

md_diff

| Parameter | Description | |---|---| | before_path | Path to the before/original markdown file (.md or .markdown) | | after_path | Path to the after/modified markdown file (.md or .markdown) |

Returns a Markdown-aware structural diff grouped by heading path and block index. Use it when a normal line diff is dominated by prose reflow.

Note: md_edit, md_inspect, and md_diff support .md and .markdown files only. For .mdx files, use the built-in edit tool (normalization still applies automatically).

How it works

Normalization path (fixes edit calls transparently):

LLM calls edit() on .md file
  → pi-mdiff intercepts tool_call
  → normalizes SEARCH block to paragraph granularity
  → built-in edit runs with normalized text
  → if still fails: normalized findInMarkdown(), writes file, returns success

Block-anchor path (md_edit, most robust):

LLM calls md_edit()
  → parse file into mdast AST
  → find section by heading (case-insensitive)
  → locate nth block node
  → splice at exact character offsets
  → write file

Structural review path (md_diff):

LLM calls md_diff(before, after)
  → parse both files into section/block maps
  → compare heading paths and block indices
  → report section/block changes with line ranges

Eval coverage

npm run eval   # 79 cases, 100% pass rate

| Category | Cases | Covers | |---|---|---| | normalize | 20 | Tables, frontmatter, fences, lists, blockquotes, headings, setext, unicode | | find | 10 | 2-line/3-line reflow, reverse reflow, flowmark vs 80-char, multi-paragraph, no-match | | md_edit | 30 | All 7 operations, blast-radius, frontmatter, section ops, error cases | | reflow | 9 | 3×3 format matrix — all 6 off-diagonal mismatches recover correctly | | edge | 10 | Empty files, preamble, duplicate headings, long paragraphs, inline code |

Next steps

pi-mdiff currently focuses on reliable prose edits and structural review for Markdown. Broader agent/documentation workflows could still benefit from:

• Formatter-aware writing: detect the file's wrapping style and reflow inserted prose to match it.
• Structural table and list operations: update a table cell, insert a list item, or move list items without exact text matching.
• MDX-aware block editing: parse MDX safely and treat JSX nodes as protected structural blocks.
• Intent-level search: add md_find/md_query for prompts like "find sections that mention auth tokens".
• Markdown validation: check links, duplicate anchors, malformed tables, and frontmatter after edits.

Development

git clone https://github.com/trycedar0x/pi-mdiff
cd pi-mdiff && npm install
npm test          # 67 unit tests
npm run eval      # 79 scenario evals
npm run typecheck # strict TypeScript check
pi -e ./src/index.ts  # load in pi for manual testing