← Sam Zoloth
Margin
Shipped for macOS · Download on GitHub

Margin turns your feedback into your AI’s style guide

A Markdown reader for the Mac. Mark a line that sounds like AI, say what’s wrong, and it becomes a rule Claude follows on the next draft.

Select a phrase that sounds like AI, or just watch.

sample-ai-draft.md
Sample AI draft

Onboarding is the product

Most teams treat onboarding as a checklist. It’s worth noting that the first session decides whether anyone comes back. This isn’t a design problem. It’s a patience problem. Teams that leverage a short, guided first run keep more of the people who sign up.

In the app

The whole loop in thirty seconds

The same loop in the Mac app, on a sample draft.

  1. Read the draft. AI writes fluently, and it still doesn’t write like you.
  2. Mark what’s wrong. Highlight the line and say why in a margin note.
  3. Feedback becomes a rule. The note turns into a writing rule with a severity and an example.
  4. Claude checks your rules before it writes. The writing guard catches the pattern and Claude rewrites.

A 30-second film of Margin: an AI draft line uses the pattern “you don’t need to ship, you need to understand”; it is highlighted in Margin with a note on why it sounds like AI; the note becomes a writing rule, one of 356 from Sam’s own corrections; and Claude’s next draft is caught by the writing guard and rewritten.

The rest of the app

A reader first, then a memory

If the tool doesn’t feel good to sit in, you won’t annotate. If you don’t annotate, your AI never learns. So Margin is a real Markdown reader before it is anything else.

A page worth sitting in

A 65-character measure and generous line height, with font size, spacing and width you can tune. Tabs, a table of contents from your headings, light and dark, and full-text search across every document.

Your markdown files become pages.
.md · .markdown · .mdown · .mkd

Highlights that survive edits

Highlight in color and attach a margin note to any highlight. When the file changes, Margin finds each highlight again in four tries.

1exact position
2text plus context
3text only
4orphan, kept for you

Praise counts too

Tag a correction as corrective, a pattern to avoid, or positive, writing to emulate. Nine writing types, from email to PRD to cover letter, keep each rule scoped.

positive

“This opening is exactly the right energy: conversational, mid-thought, no preamble.”

corrective

“Never use ‘furthermore’. It’s an AI transition tell.”

Claude can’t write what you’ve banned

Switch on the writing guard in Settings and Margin generates a Claude Code hook from your rules. It never touches your Claude or Codex setup unless you do. When Claude tries to write a kill word or an AI-slop pattern into a prose file, the hook rejects the edit before it lands. A bundled MCP server gives Claude your documents, annotations, corrections and rules, and Send to Claude pushes annotations straight in.

The rules come back in the reader too. A reviewed rule underlines its matches in whatever you have open, and the card in the margin offers a one-click replace.

BLOCKED: ‘leverage’ violates your writing rules

Review AI edits one change at a time

When Claude edits a file you have open, Margin notices. Edits under 5% of the document are accepted quietly. Larger ones show a diff with keep or revert on each change.

+ Your AI should write like you.
- Your AI should leverage synergies.
↑ Keep   ↓ Revert   ⌘Z Undo all
Evals

Rules only count if the next draft follows them

Margin ships with a harness that tries to tempt the model: 27 prompts across nine writing types, scored by a mechanical checker and a model grader against your rules.

On top of it runs an optimization loop. An agent changes the coaching prompt one idea at a time, reruns all 27, and keeps or reverts the change with a git commit. Each round takes about ten minutes, so it runs overnight.

Halfway through, I found the checker caught only 4% of what I flag by hand. I corrected 27 samples in Margin the way I would any draft, added the six kinds of check it was missing, and the score fell. That was the point.

8prompt architectures tested head to head
4% → 41%of my own corrections the checker catches
500+samples scored
Run · hypothesisPass rate
001
Baseline: rules only
51.9%
004
Hybrid: corrections plus high-signal rules
76.9%
008
Calibrated checker
46.4%
012
Length limits and more prohibitions
70.4%

Four runs from the trace. Every run records its hypothesis and whether it was kept, and the loop commits its own results, so the history can be audited.

Design

Marginalia moves like paper

The palette is warm and editorial: off-white paper, near-black ink and one amber accent, so it feels closer to a printed page than a dashboard. The motion follows one law from Emil Kowalski: the more often a gesture happens, the less it animates. The demo at the top uses the app’s own timings.

Frequent gestures get small budgets

Saving a note, hovering a dot or recoloring stays under 150 ms. Opening a thread or a rule card stays under 250 ms. Only rare moments, like opening a document, get up to 400 ms. Typing and scrolling get none.

Notes enter like paper, never bounce

Surfaces that carry text arrive with a blur, a fade and a small shift, never an overshoot. A saved note blurs in over 140 ms, and a closing card fades back toward its anchor so your eye stays where it was.

A highlight swells once, then goes quiet

A new highlight gets one brief warm swell, 550 ms, then stays still. Pulsing annotated text forever would compete with the words.

The database is the truth

Rules live in a local SQLite database. writing-rules.md and the writing guard are generated from it, so rules can be counted, edited and reached from the app, the MCP tools and the command line.

Paper, sidebar, ink and amber, the five highlight colors, and the must-fix red. Every color has a warm dark variant, which this page uses too.
NewsreaderThe reading face, at a 65-character measure.
Instrument SansThe interface.
JetBrains MonoCode and file paths.
Why I built it

Why I built Margin

AI keeps getting better at writing, but it still can’t write like me, and there’s no easy way to capture my voice and keep my feedback. In Margin, feedback I give once gets generalized and reused instead of lost.
Sam Zoloth

Your editorial taste stays on your Mac

  • Your Markdown files stay where they are on disk.
  • Highlights, notes, corrections and rules live in one SQLite file, ~/.margin/margin.db. No account and no sync service.
  • Your rules export to ~/.margin/writing-rules.md, a plain file you can read and edit.

What reaches Claude, and when

  • Turning corrections into rules runs through Claude.
  • When you connect the MCP server, Claude can read your documents, annotations and rules.

Margin checks GitHub for updates when it opens. Updates are code-signed and notarized.