markdown-markdown

Local Markdown review and annotation CLI.

Point it at a single Markdown file or a directory of Markdown files, review them in the browser, then hand the structured result back to an AI system or another automation step.

Companion Skill

If you want agent instructions for using this CLI, install the separate markdown-markdown-skill repository. This package stays focused on the CLI and browser runtime.

Install

npm install markdown-markdown

Or run it without a permanent install:

npx markdown-markdown review create --browser system ./docs/spec.md

Development Setup

npm install

Build

npm run build

This produces:

• dist/cli.js for the command-line entrypoint
• dist/index.js for shared exports
• dist/web/ for the browser UI

Release

Releases are handled by GitHub Actions. Push a tag that starts with v such as v0.1.1, and the workflow will build and publish the package to npm.

The workflow uses GitHub Actions trusted publishing, so no npm token needs to be stored in the repository.

Use

Async review loop

The primary agent-facing flow is asynchronous:

npx markdown-markdown review create --browser system ./docs/spec.md

review create starts a single active review session, opens the browser UI, and prints a JSON payload with:

• sessionId
• reviewUrl
• controlUrl
• publicUrl
• round
• phase

Then the agent waits for user action:

npx markdown-markdown review wait

When the user clicks Finish review, review wait returns a finish_review payload.

When the user clicks Continue reviewing after changes, review wait returns a continue_review payload. After the agent edits files, it should request the next round:

npx markdown-markdown review refresh

When the session is done, clean it up explicitly:

npx markdown-markdown review close

The browser UI keeps the document readable during continue_review, but it locks annotation edits until the next round is refreshed. The browser tab title also follows the current file name and review status, which helps when you have multiple tabs open.

Markdown image assets can be local relative paths or remote URLs. Local assets are served through the review host so regular Markdown image references keep working in directory mode. Placeholder figure markers such as ![Figure 4](assets/figure-placeholder.svg) are rendered as centered text labels instead of oversized preview art.

Legacy one-shot mode

npx markdown-markdown ./docs

or

npx markdown-markdown ./docs/spec.md

To open the session in the system default browser instead of the compact app-style window, use:

npx markdown-markdown --browser system ./docs/spec.md

To force a Cloudflare public URL and fail fast when cloudflared is missing:

npx markdown-markdown --cloudflare ./docs/spec.md

To force localhost only, even if cloudflared is installed:

npx markdown-markdown --no-cloudflare ./docs/spec.md

To write the final review JSON and a lightweight lifecycle status file for agents to poll:

npx markdown-markdown --output ./out/review.json --status-file ./out/review.status.json ./docs/spec.md

The CLI will:

• discover Markdown files
• launch a local web session
• use a public Cloudflare tunnel when cloudflared is installed, unless you pass --no-cloudflare
• fail fast with a clear install message when you pass --cloudflare but cloudflared is missing
• let you annotate headings, paragraphs, blockquotes, lists, tables, code blocks, images, and horizontal rules
• support two review actions in the browser: Finish review and Continue reviewing after changes
• print the structured review result to stdout
• optionally write the final JSON to --output
• optionally write running/completed/failed status snapshots to --status-file

Output

The review result JSON includes:

• rootPath
• mode
• files
• annotations
• prompt
• submittedAt or abandonedAt
• action when the user submits (finish_review or continue_review)
• round

The prompt field is a ready-to-send Markdown summary of the requested changes, grouped by file with short anchor text and line ranges so an AI can locate the target block without extra token cost.

If you use --status-file, the agent-friendly lifecycle file will move through:

• running
• completed
• failed

That file is the simplest way to know when an asynchronous caller should consider the review finished.

Development

• npm run dev runs the Vite UI in demo mode
• npm run lint runs TypeScript checks
• npm test runs the test suite

If the app cannot reach the local review service during development, it falls back to a built-in demo session so you can still work on the UI.