A shared surface for humans and AI agents to think and write together.
I built coauthor because I was frustrated with how I work with AI on documents.
I use AI daily for product specs, strategy docs, planning, and reviews. The AI is good at producing content. The problem is everything that happens after — the part where I shape it into something I'd actually ship.
In a chat-based workflow, I read what the AI wrote, then type corrections into the terminal. "The third section is wrong." "Cut this in half." "Reframe the whole thing." The AI regenerates the entire document. Sometimes it fixes what I asked for and breaks something I liked. I re-read everything to check. I find another issue. Another round-trip. Another full regeneration.
Three things drove me to build this:
I couldn't point at things. The document lived in chat output or a terminal scroll buffer. I couldn't highlight a paragraph, a table row, a specific claim and say "this — this is the problem." I had to describe what I meant in words and hope the AI matched it to the right part. Half the time it changed the wrong section.
Good parts kept getting overwritten. I'd read a section and think "this is solid, don't touch it" — but I never told the AI. On the next pass, it rewrote everything, including the parts that were already right. There was no way to protect what was already good.
I kept repeating myself. I'd give the same feedback on section 5, then section 12, then section 31. The same principle, applied one paragraph at a time, because there was no way to say "this applies to everything, from now on."
A surface where I can see the document, point at the parts that matter, and leave feedback the AI can actually read and act on. Not a chat window. Not a diff viewer. A place where both of us — human and AI — work on the same file.
Three interactions turned out to be enough:
Edit — you know the fix, you make it yourself. A typo, a wrong number, a sentence that needs rewording. Click, change the markdown, save. The file updates on disk. No round-trip through the AI for things you can do faster.
Comment — you know what's wrong but want the AI to handle it. Click Comment, a popup opens with the section name: "What should change?" You write feedback in plain language. It saves to a .coauthor file that the AI reads on its next pass. The AI sees exactly which section you're talking about. No ambiguity.
You can also select any text to comment on a specific phrase. And click + Direction in the toolbar for feedback that applies to the entire document — "make everything shorter," "reframe from the customer's perspective."
Keep — this section is good. Don't touch it. One click. Green border. On the next iteration, the AI sees the approval and leaves it alone. Good parts stay good.
Each layer builds on the one below it:
Layer 1: The file. Both human and AI edit the same markdown file on disk. This is the foundation — no sync, no API, no platform. Just a file. Edit gives you direct access to it.
Layer 2: The sidecar. When you Comment or Keep, feedback saves to a .coauthor JSON file next to the document. Structured, anchored, readable by any AI agent. The file stays clean, the feedback stays separate.
Layer 3: History. Every time the AI writes to the file, the previous version snapshots to .history/. You can diff any two versions and cherry-pick what was removed. History builds on Layer 1 — it watches for file writes and captures the before state.
Layer 4: Principles. The .coauthor format supports standing rules — instructions that persist across iterations. You can add them manually ("always frame as actions, not features") or the AI agent can propose them after noticing patterns in your feedback. Principles build on Layer 2 — they live in the same .coauthor file alongside your entries.
Layer 5: Auto-reload. AI updates the file from terminal, browser refreshes automatically. The collaboration loop closes — you see changes without switching windows.
Each layer is independently useful. You can use coauthor as just an editor (Layer 1). Add comments and it becomes a review tool (Layer 2). The AI writes back and you get history (Layer 3). Over time, shared understanding accumulates (Layer 4). The loop tightens (Layer 5).
The .coauthor file that stores your feedback — comments, approvals, principles — is a simple JSON sidecar that sits next to the document. This is deliberate. It makes feedback a first-class artifact, not something buried in chat history or locked inside a specific tool.
{
"version": "1.0",
"file": "spec.md",
"entries": [
{
"id": "a1",
"anchor": "We recommend React Native",
"content": "Team has no mobile experience. Consider Flutter instead.",
"status": "open"
},
{
"id": "a2",
"anchor": "## Goals & Success Metrics",
"approve": true,
"status": "resolved"
}
],
"principles": [
{
"id": "p1",
"content": "Keep every section under 100 words.",
"origin": "human",
"accepted": true
}
]
}An entry is just anchor (what part) + content (what you think). No type classification — the human doesn't pick from a dropdown. The AI interprets intent from natural language. "Delete this section" and "this needs more detail" are both just content. The AI figures out the action.
Principles are standing instructions that persist across iterations. You state them explicitly, or your AI agent can propose them after noticing patterns in your feedback.
It's portable. Email it, commit it to git so feedback travels with the code, pass it between AI agents, aggregate from multiple reviewers. It's not locked to coauthor the tool — any AI that reads JSON can consume a .coauthor file.
It works across tools. Start a review in coauthor, switch to chat for quick fixes, come back to coauthor for precise feedback. The .coauthor file persists regardless of which tool you use. Claude Code, Cursor, Copilot — they all read files. The format is the protocol.
It separates feedback from the document. The document stays clean. The feedback stays structured. Neither pollutes the other. And when you're done, --clean removes the artifacts and your document is exactly as it was.
See SPEC.md for the full format specification.
npx coauthor-review --demoOpens a sample document with pre-populated feedback — an approved section, open comments, a pending principle. See what a real review session looks like in 5 seconds.
npx coauthor-review ~/my-project/specs # A folder
npx coauthor-review ./quarterly-plan.md # A single fileWorks with any markdown files — AI-generated, hand-written, or pulled from a repo. No AI agent needed. coauthor is a clean markdown reviewer with inline editing. The .coauthor feedback file only gets created when you add comments or approvals.
Your AI generates a document. You want to review it properly instead of scrolling through terminal output.
With Claude Code:
> "Write a product spec for the onboarding flow"
# Claude generates the spec
> "Open in coauthor"
# Claude saves it to ~/coauthor-sessions/onboarding-spec/
# Starts the server, opens your browser
# You review — edit, comment, keep sections, add direction
> "Check feedback"
# Claude reads your edits + .coauthor file
# Incorporates everything, coauthor auto-reloadsContent saves to ~/coauthor-sessions/ and persists across conversations.
With Cursor / Copilot / any AI agent:
# Terminal 1: coauthor
npx coauthor-review ~/my-project/specs
# Terminal 2: your AI agent
# AI writes .md files → they appear in coauthor automatically
# You review in browser, leave feedback
# AI reads your edits from .md + comments from .coauthorcoauthor and chat coexist. Use coauthor when you want precision — anchored comments, approvals, principles. Use chat when you want speed — "just fix section 3." The AI mentions open .coauthor feedback if it exists, but doesn't force you to use it.
Send two files:
spec.md ← the document
spec.coauthor ← your comments, approvals, and principles
The recipient opens them in coauthor. Their AI agent reads the .coauthor file and acts on your structured feedback directly. No email thread. No "see my comments in the attached doc."
npx coauthor-review --clean ~/my-project/specsRemoves .coauthor files and .history/ snapshots. Documents stay untouched. Warns if you have unresolved comments.
No database. No cloud. No account. Edit in the browser — the markdown file changes on disk. Add a comment — a .coauthor file appears next to it. Close the server — your files are right where they were. Nothing is copied, uploaded, or stored anywhere else.
your-project/
spec.md ← Your document
spec.coauthor ← Feedback (created when you comment)
.history/
spec_2026-04-11.md ← Snapshot (created when AI updates)
Add one instruction to your AI agent (CLAUDE.md, .cursorrules, system prompt):
When editing a markdown file, check if a .coauthor sidecar exists (same name,
.coauthor extension). If it has status: "open" entries, mention it once and ask
whether to incorporate the feedback or continue in chat mode. Don't block on it.
For Claude Code, install the /coauthor skill:
mkdir -p ~/.claude/skills/coauthor
curl -o ~/.claude/skills/coauthor/SKILL.md \
https://raw.githubusercontent.com/abhitsian/coauthor/main/SKILL.mdThen say /coauthor to open any file for review, or "open in coauthor" after generating content.
npx coauthor-review [path] # review
npx coauthor-review --demo # try it
npx coauthor-review --clean [path] # clean up
npx coauthor-review --port 8080 # custom portFiles, not a database. AI agents work with files. coauthor meets them there.
Sidecar, not inline. Inline comments pollute the document and confuse AI agents.
Snapshot on AI writes only. Human edits are shaping. History matters when the AI produces a new generation.
Local. Your specs are confidential. Nothing leaves your machine.
- Not Google Docs. No multi-cursor. One human + one AI agent.
- Not a CMS. No publishing, templates, or workflows.
- Not an AI product. Doesn't call any AI APIs. Bring your own agent.
MIT