coauthor

name	coauthor
description	Open a file or folder in coauthor — the shared review surface for human + AI collaboration. Serves markdown files with inline editing, commenting, and version history. Use when reviewing specs, plans, or documents collaboratively.
when_to_use	Use when the user says 'open in coauthor', 'review this', 'let's coauthor this', 'coauthor this', or wants to collaboratively review/edit documents with inline feedback. Also use when the user wants to review content that was just generated in the conversation.
argument-hint	<file path, folder path, or omit to save current content>
arguments	["path"]
allowed-tools	["Bash","Read","Write","Edit","Glob"]

coauthor — Collaborative Review Mode

Open content in coauthor for human-AI collaborative editing.

Step 1: Determine what to open

Three scenarios:

A. User provides a file or folder path

• File path (e.g., ~/specs/plan.md) → serve its parent folder
• Folder path (e.g., ~/specs/) → serve that folder

B. Content was just generated in this conversation

If the user says "open in coauthor" or "coauthor this" after you've produced content (a spec, plan, review, analysis, etc.):

1. Create a folder at ~/coauthor-sessions/ if it doesn't exist
2. Create a subfolder with a descriptive name based on the content (e.g., widget-repository, june-planning, onboarding-spec)
3. Write the content to a .md file in that folder
4. Serve that folder

mkdir -p ~/coauthor-sessions/<topic-name>
# Write the content to the file using the Write tool
# Then serve the folder

C. No path and no recent content

Ask the user: "What would you like to review? Give me a file path, folder, or I can save our recent discussion to a file."

Step 2: Start coauthor

# Kill any existing coauthor instance
lsof -ti:3847 | xargs kill -9 2>/dev/null

# Option A: if cloned locally (preferred — faster)
node ~/coauthor/server.js "<target_folder>" &
sleep 1
open http://localhost:3847

# Option B: via npx (if not cloned)
npx coauthor-review "<target_path>"

If port 3847 is in use, try 3848, 3849, etc. with --port flag.

Step 3: Confirm to user

Tell the user:

• coauthor is running at http://localhost:3847
• Which files are available in the sidebar
• Remind them of the actions:
  • Edit — fix it yourself (typos, numbers, rewording)
  • Comment — tell the AI what to change and why
  • Keep — approve a section (AI won't touch it)
  • + Direction — document-wide feedback
• Say: "When you're done, tell me 'check feedback' and I'll incorporate everything."

Step 4: Check feedback

Trigger: Any of these signals mean the user wants you to read their feedback:

• Explicit: "check feedback", "incorporate feedback", "read my comments"
• Implicit: "done reviewing", "ok I reviewed it", "looks good with some changes", "I made some edits", "what do you think now"
• Continuing work: If the user asks you to modify the same file you opened in coauthor, ALWAYS check for a .coauthor file first before making changes. Their feedback takes priority.

Auto-detect: Before editing any markdown file that has a .coauthor sidecar next to it, read the sidecar first. If it has status: "open" entries, mention them: "I see you left 3 comments on this file — incorporating those first."

1. Read the .coauthor file:

   cat <target_folder>/<filename>.coauthor
   

2. Read the markdown file (user may have made inline edits):

   cat <target_folder>/<filename>.md
   

3. Process entries:

   • status: "open" entries with content → incorporate the feedback into the markdown
   • approve: true entries → don't modify those sections
   • Entries with no anchor → apply as document-wide direction
   • Check principles array → apply all accepted: true principles to every change

4. Look for patterns. If 3+ entries suggest a consistent preference, propose a principle:

   {
     "id": "p1",
     "content": "The derived principle",
     "origin": "derived",
     "basis": "Entries a1, a3, a5 all suggest...",
     "accepted": null
   }
   

5. Update the markdown file. coauthor auto-reloads in the browser.

6. Set processed entries to status: "resolved".

7. Tell the user what was changed, what was kept, and any derived principles for their review.

Notes

• coauthor serves files from disk. Both human (via browser) and AI (via Claude Code) edit the same files.
• History snapshots are created automatically in .history/ when the AI updates a file.
• The server auto-reloads the browser when files change externally.
• The .coauthor format spec is at ~/coauthor/SPEC.md
• Session files are saved at ~/coauthor-sessions/ — these persist across conversations.