track-changes

What is track-changes?

track-changes is a three-skill suite for Claude Code. The core track-changes skill watches every change Claude makes to your tracked .md, .qmd, and .tex files: each AI-introduced edit is wrapped in a <mark> highlight followed by a small reference number — rendered as a yellow span (with a strikethrough overlay for anything deleted) in any markdown viewer — so you can review every change individually and accept or reject it, the way you would with Track Changes in Word or Suggesting mode in Google Docs. The companion verified-import skill (installed alongside) adds the /tc import command for bringing in vetted source material without unnecessary highlights. The tc-polish skill adds the /tc polish command for cleaning up voice-dictated prose — speech-recognition errors, grammar, dropped words — surfacing every fix as an ordinary track-changes mark you review the same way.

Why it exists

Vetted documents — lecture notes, exams, manuscripts — have often been refined by their author over years. When an AI assistant rewrites part of one, the changes are invisible: they blend into text you already trust, and you have no easy way to tell what the AI touched. A single quiet, wrong change can undermine confidence in the whole file.

track-changes makes every AI change visible and reversible. It refuses to let Claude save an edit to a tracked file unless the changed characters are wrapped in a highlight you can see, and it records each highlight — and every later accept-or-reject decision — in a plain-text log kept alongside the document. You stay the author; the AI is a copy-editor whose work you sign off on, change by change.

Prerequisites

Claude Code must be installed and working. track-changes is a Claude Code skill — it runs inside Claude Code, not separately. Install Claude Code first if you haven’t already. The skill also needs Python 3 and curl available on your system (both are present on most setups by default).

Installation

1. Start a Claude Code session — anywhere; track-changes installs into your user profile, not a specific project.
2. Give the install link to Claude Code. Type:
   Read https://mgkay.github.io/track-changes/bootstrap.md and follow the installation instructions inside it.
3. Confirm. Claude Code downloads all three skills (track-changes, verified-import, and tc-polish), wires them into your configuration, and reports success.
4. Open a new Claude Code session so the skill takes effect.

Turn it on for your files

track-changes is off by default — it ignores every file until you explicitly opt in. Nothing is tracked until you say so, and you opt in per folder or per file.

The usual way is to mark a whole folder of source files at once. From inside Claude Code:

/tc mark /path/to/your/lectures

That drops a small marker file named .tc-tracked in the folder. From then on, every .md / .qmd / .tex file in that folder is tracked. The marker only covers its own folder — it does not reach up to parent folders or down into subfolders, so you stay in control of exactly what is watched. To track a subfolder too, mark it separately. To track just one file instead of a whole folder, use /tc enable <file> (explained under Commands below).

Example: an AI edit, reviewed

The boxes below render the actual highlight markup — this is what you see in VS Code’s built-in markdown preview (Ctrl+Shift+V) or any viewer that displays markdown.

1. Your original sentence (on disk)

2. Claude proposes two changes

Change 1 inserts the word “often.” Change 2 strikes through “the optimal” and proposes “a near-optimal” in its place. Claude was allowed to save this only because every altered character sits inside a highlight; an unmarked edit would have been refused. Each small number is a handle you use in the next step.

3. You decide: keep #1, drop #2

Just tell Claude in plain English — “accept 1, reject 2” — or run /tc accept <file> 1 and /tc reject <file> 2. (You can also delete the highlight wrappers by hand in any editor; nothing is locked.)

4. The result (on disk)

The accepted change stayed; the rejected one was rolled back to your original wording. Both decisions — with timestamps and the old and new text — were appended to a log file named .tc-history.md in your project. Because that log is plain text kept in version control, tools like git diff and git blame surface AI-attributed changes naturally, even months later.

How it works

You don’t run track-changes during normal work — once installed, it watches for edits on its own. Three things happen automatically behind the scenes:

• It checks every save before it happens. Whenever Claude is about to write to a tracked file, track-changes first inspects what would change. If any new or altered text isn’t wrapped in a highlight, the save is refused and Claude is told to mark it. (This kind of automatic, behind-the-scenes check is called a hook — Claude Code triggers it for you; you never invoke it yourself.) The practical effect: an AI edit can never land in your document unhighlighted.
• It keeps a running log. Every highlight Claude adds, and every accept-or-reject decision you make afterward, is appended to the plain-text .tc-history.md file next to your document. Since the log travels with your project, you — or a co-author, or a reviewer — can always see what the AI touched and what you decided.
• It stays out of the way otherwise. On files you haven’t opted in, and in any turn where you’ve paused it, the checks do nothing at all. There is no separate app or window; it lives entirely inside your normal Claude Code session.

Commands

The suite adds two top-level slash commands to Claude Code: /tc and /draft. /tc takes a subcommand — including /tc import and /tc polish, which reach the cooperating verified-import and tc-polish skills. Here is the full set, grouped by what you’re trying to do (/tc import has its own section below).

Turning tracking on and off

• /tc mark [<dir>] — Turn tracking on for an entire folder by dropping a .tc-tracked marker in it. This is the usual way to start. With no folder given, it marks the current one.
• /tc enable <file> — Turn tracking on for a single file (it adds tc-track: true to the file’s header). Use this when you want just one file watched rather than its whole folder.
• /tc disable <file> — The opposite: explicitly exclude one file from tracking, even if its folder is marked.
• /tc status [<file>] — Show whether a file is currently being tracked and why (which rule turned it on or off). Use it when you’re not sure a file is being watched.

Pausing for one request

• /draft — Suspend tracking for just your next message to Claude, then it switches back on by itself. Use it when you’re asking for a large rewrite or a brand-new draft that would be too noisy to highlight line by line — you want the writing for that one step, not the marks. (/tc draft does the same thing.)

Cleaning up voice-dictated prose

• /tc polish [<file>] — Clean up voice-dictated prose — speech-recognition slips, ordinary grammar, dropped words — in a tracked file. Every fix lands as an ordinary highlight you review with /tc accept / /tc reject, exactly like any other change. It never rewrites a token it can’t recognize as plain prose (jargon, code, math, a domain term): it leaves that untouched and flags it for you instead. On an untracked file it offers a one-time direct cleanup (no marks) or to enable tracking first. (Part of the tc-polish skill.)

Bringing in trusted source material

• /tc import <source>[#L<a>-L<b>] [<target>] — Insert vetted material — a section of an old notebook, a prior manuscript, a chapter — into a tracked document. Claude converts it to the document’s format and it lands clean (no highlights), because faithfully reproduced source isn’t an AI edit you need to review; Claude marks only a genuinely significant change (one that alters meaning), while minor reformatting stays clean. See the fuller walkthrough below. (Part of the verified-import skill.)

Reviewing and resolving changes

After Claude has marked up a file, these let you work through the highlights quickly instead of editing each wrapper by hand.

• /tc list <file> — List every highlight in the file by number, each with a short preview of what changed. The natural starting point for a review pass.
• /tc accept <file> <ranges> — Keep Claude’s version for the listed highlights and remove the wrappers, making the text final. Ranges are flexible: 1-25,!7,!11 means “marks 1 through 25, except 7 and 11.”
• /tc reject <file> <ranges> — The opposite: discard Claude’s version, restore your original text, and remove the wrappers. Same range syntax.
• /tc accept-all <file> / /tc reject-all <file> — Resolve every highlight in the file at once, when you’ve decided wholesale.

What else it can do

Beyond the basic mark-and-review loop, track-changes handles the situations that actually come up when you build documents with an AI’s help.

Build from material you already trust — without drowning in highlights

Most of a new lecture or chapter is assembled from things you’ve already written and vetted: a section of an old notebook, a prior manuscript, a trusted reference. Only a little is genuinely new AI writing. If every imported paragraph were highlighted, the handful of lines that actually need your attention would be buried in yellow. The companion verified-import skill handles this with the /tc import command:

/tc import chapter3.md#L10-L42 lecture-notes.md

Claude converts the source into the target document’s format and inserts it, reproducing the content faithfully. A verified import lands clean (no highlights) by default, so it reads as ordinary prose and only Claude’s genuinely new writing around it gets highlighted. Claude uses its judgment: if a conversion introduces a genuinely significant change — an added or removed sentence or clause, or a changed quantity, term, or formula — it highlights just that change for your review; minor differences (reflow, formatting, equivalent notation) stay clean. The command works on text sources; binary formats require a plain-text copy to import from.

Resolve a whole review pass in seconds

A heavy editing session can leave dozens of highlights. Rather than clicking through them one at a time, list them and then accept or reject in ranges — for example, keep everything except the two changes you disagree with. See /tc list, /tc accept, and /tc reject above.

Add brand-new sections without breaking the page

Wrapping a brand-new heading or code block in an inline highlight would break how the document displays. In Markdown and Quarto, a new heading, fenced code block, or callout is flagged with a single marker on the line just above it — you still see at a glance that it’s new, and the document still renders correctly. For LaTeX, a brand-new \section or environment uses /draft instead (write the structure first, then let track-changes mark any content Claude adds inside it).

Hand the document to a reader, cleanly

When you share the document for someone to read rather than review, you don’t want yellow highlights all over it. Add ?clean=1 to the end of the shared link and the rendered page hides every mark and reference number. The underlying file is untouched, so your review state is fully preserved — the clean view is just for the reader.

Catch half-finished edits before they’re committed

If you keep your documents in git, track-changes can optionally warn you at commit time when a file still has unresolved highlights in it — a safety net so partly-reviewed AI edits don’t slip into your project’s history by accident. It’s off until you switch it on, and you can always override it for a single commit.

Pre-clean voice dictation in your editor — decap

Voice dictation often sprinkles stray capital letters mid-sentence. The suite bundles a small companion tool, decap, that strips them — a deterministic filter that lowercases stray mid-sentence capitals while leaving sentence starts, acronyms, camelCase, and protected terms alone. Because you run it in your editor and it never goes through Claude, its edits are deliberately not tracked — exactly what you want for a bulk, judgment-free cleanup of your own dictation. Run it on fresh dictation before the text is marked (it is text-only and not aware of <mark> spans). It pairs naturally with /tc polish: decap for the instant mechanical pass, /tc polish for the deeper editorial pass you review as marks.

Installation. decap installs automatically when you run the bootstrap — the tool lands at ~/.claude/skills/track-changes/tools/decap.py, so there is nothing extra to download. The one piece the bootstrap can’t do is bind it to a key in your editor — and since you’re already in Claude Code, the easiest way is to let Claude do that for you. Paste this:

Set up the bundled decap tool as a VS Code keybinding. Install the
"Edit with Shell Command" extension (ryu1kn.edit-with-shell) if it isn't
already installed; add an editWithShell.favoriteCommands entry with id
"decap" that runs:  python ~/.claude/skills/track-changes/tools/decap.py
(use the full absolute path if ~ isn't expanded on my OS); set
editWithShell.quickCommand1 to "decap"; and bind ctrl+alt+c to
editWithShell.runQuickCommand1 in keybindings.json.

That installs a small VS Code extension and binds Ctrl+Alt+C to run decap on the current selection — select fresh, unmarked dictation and press it. Prefer to wire it up by hand, or use a different editor (Vim, Emacs)? Ask Claude for the manual steps, or see SKILL.md in the project repository.

Good to know

• It shows up wherever you already read. Highlights are stored as small standard HTML tags right inside your document, so they appear in VS Code’s preview, on GitHub, in Quarto output, and in common markdown viewers — no special tool required to see them.
• The record lives in your project. The audit log is plain text in your project folder and is meant to be committed to version control, so the AI’s edit history is part of your normal project history.
• It supports .md, .qmd, and .tex. LaTeX files use an equivalent \tc{...} markup instead of <mark>, so highlighted changes survive a PDF build.
• It’s light and quiet. The background checks add only a fraction of a second per edit, and do nothing at all on files you haven’t opted in.

Learn more

The full installer manifest is in bootstrap.md. Source files and the complete file list live in the project repository.