changedown

ChangeDown

Track changes in markdown — for humans and AI agents.

ChangeDown brings popular editor-style track changes to markdown. Edits are inline CriticMarkup with metadata in standard markdown footnotes — visible in any text editor, diffable in git, readable by any AI agent. A VS Code extension and AI agent plugins enforce author, timestamp, and rationale on every change. Discussion threads capture disagreement and resolution inline.

One format, everywhere — CriticMarkup is plain text. Readable in any editor, diffable in git, parseable by any agent. No proprietary format, no lock-in.

The workflow you know — Accept, reject, comment, navigate. The muscle memory from popular editors, applied to markdown.

Human-AI parity — Humans and agents make changes the same way, in the same format. Review an agent's work exactly like you'd review a colleague's.

---

The Gap

Today, if you want to understand why a line looks the way it does, you have to leave the file. git log tells you what changed. git blame tells you who. But the reasoning — the discussion, the alternatives considered, the decision — lives in PR comments, Slack threads, issue trackers. Each hop requires a different tool, different auth, different search. For an LLM reading the file, most of those hops are impossible.

ChangeDown closes this gap. The file carries its own deliberation history. Anyone reading it — a new team member, a code reviewer, an AI agent — sees not just the current state but the reasoning that produced it.

---

For Humans and Agents

For Humans (VS Code / Cursor)	For Agents (Claude Code / OpenCode / Cursor)
Tracking mode — type normally, edits auto-wrap in CriticMarkup	6 MCP tools — propose, review, amend, supersede, list, read
Smart View — hides markup delimiters for clean reading	Super-efficient compact protocol — LINE:HASH coordinates + edit DSL, 2.3× fewer tokens
Accept / Reject — resolve changes with keyboard shortcuts	Concurrent multi-agent editing — hash-verified coordinates prevent stale reads and silent conflicts
Review panel — browse changes, discussion threads, settings	Built-in review workflow — review_changes tool with agent-native metadata projection
Per-author colors — distinguish contributors at a glance	Policy hooks — enforce tracking on every edit (strict, safety-net, or permissive)
SCM integration — native VS Code comments and change tracking	Batch operations — atomic multi-change proposals with grouped IDs
Export to DOCX — share tracked documents with Word users	Skill file — workflow guidance loaded into agent context
Four view modes — all markup, simple, final, original	Three platforms — Claude Code plugin, OpenCode plugin, Cursor MCP

Quick start guide: docs/public/DEMO.md | Deep dive: ChangeDown and Hashlines Explained

Install

Quick start

npx changedown init

Interactive setup: detects your editors and agents, creates .changedown/config.toml, installs extensions, and opens a getting-started tutorial.

For humans

VS Code — search ChangeDown in the Extensions marketplace

Cursor — search ChangeDown in the Extensions panel

Marketplace listing coming soon. For now, install manually:

git clone https://github.com/hackerbara/changedown.git
cd changedown
npm install && node scripts/build.mjs

# VS Code
code --install-extension packages/vscode-extension/changedown-*.vsix

# Cursor
cursor --install-extension packages/vscode-extension/changedown-*.vsix

For agents

Claude Code

/plugin install changedown@hackerbara

OpenCode — add to your project's opencode.json:

{
  "plugin": ["@changedown/opencode-plugin"]
}

Cursor — the install script configures MCP, hooks, and skill:

node scripts/install.mjs

From source

git clone https://github.com/hackerbara/changedown.git
cd changedown
npm install
node scripts/build.mjs
node scripts/install.mjs

CriticMarkup Syntax

Type	Syntax	Example
Insertion	text	added text
Deletion	``	``
Substitution	new	after
Highlight	text	highlighted
Comment	``	``

Changes carry metadata in markdown footnotes:

The API should use gRPC for internal services.

[^cn-1]: @ai:claude-sonnet-4-5 | 2026-02-17 | sub | proposed
    @ai:claude-sonnet-4-5 2026-02-17: gRPC reduces serialization
    overhead for internal service-to-service calls.
    approved: @james 2026-02-17 "agreed, REST is wasteful here"

You can use as much or as little of the format as you want: