szoloth/quill

Quill: Bi-directional AI writing assistant

Annotate documents with inline feedback, then let AI agents respond directly through MCP. No API keys needed — agents connect through Claude Code or Cursor's MCP integration.

Architecture

┌────────────────┐     ~/.quill/      ┌──────────────┐
│  Quill macOS   │◄──── state.json ───►│  quill-mcp   │
│  quill-tui     │◄── document.json ──►│  (MCP server) │
│  quill-web     │◄─ agent-response ──►│              │
└────────────────┘      .json         └──────┬───────┘
                                              │ stdio
                                     ┌────────┴────────┐
                                     │  Claude Code    │
                                     │  Cursor         │
                                     │  Any MCP client │
                                     └─────────────────┘

Quick start

# Annotate in Quill, then let agent work on it
/quill revise

# Or step by step:
/quill status           # Check what's loaded
/quill annotate draft.md  # Create annotations (agent-side)
/quill respond          # Address all annotations

MCP tools (available when quill-mcp server is connected)

Reading tools (agent reads from Quill)

| Tool | Description | |------|-------------| | quill_get_document | Get current document + annotations + prompt | | quill_get_annotations | List annotations (filterable by severity/category) | | quill_get_prompt | Get the ready-to-use revision prompt | | quill_get_preserved_facts | Facts that must not change during revision | | quill_status | Quick check: document loaded? How many annotations? | | quill_get_agent_responses | View previous agent responses |

Writing tools (agent writes back to Quill)

| Tool | Description | |------|-------------| | quill_respond_to_annotation | Respond to an annotation (resolve/clarify/suggest/reject) | | quill_resolve_annotation | Mark an annotation as addressed | | quill_add_annotation | Add agent feedback to the document | | quill_update_document | Push revised content back to Quill |

Resources

| Resource | URI | |----------|-----| | Document | quill://document | | Agent responses | quill://agent-responses |

Prompts

| Prompt | Description | |--------|-------------| | quill-revise | Structured revision prompt from annotations | | quill-humanize | Two-pass humanization with annotation awareness |

Core workflow

1. Annotate → Agent reads

User annotates in Quill (macOS app, TUI, or web). Agent reads via MCP:

Agent calls: quill_get_document
→ Gets document content, annotations, preserved facts, and revision prompt

2. Agent works → Responds

Agent processes each annotation and responds:

Agent calls: quill_respond_to_annotation
  annotationId: "abc-123"
  action: "suggest"
  message: "Replaced generic opener with specific context"
  suggestedText: "After six months building on Claude Code..."

Agent calls: quill_resolve_annotation
  annotationId: "def-456"
  message: "Removed redundant sentence"

3. Agent pushes → User reviews

Agent pushes revised content back:

Agent calls: quill_update_document
  content: "...revised full text..."
  summary: "Addressed 4 annotations: tightened intro, fixed voice issues"
  addressedAnnotationIds: ["abc-123", "def-456", ...]

User sees agent responses appear in Quill's sidebar with accept/reject controls.

Commands

| Command | Action | |---------|--------| | /quill status | Check if document is loaded, annotation count | | /quill annotate <file> | Analyze document and create annotations | | /quill revise | Read annotations and revise document via MCP | | /quill respond | Process and respond to all annotations | | /quill prompt | Get the revision prompt | | /quill humanize | Two-pass humanization addressing annotations |

Annotation categories

| Category | Use for | |----------|---------| | VOICE | Tone issues, AI-sounding phrases, vocabulary | | CLARITY | Vague language, unclear references | | STRUCTURE | Flow problems, paragraph organization | | EXPAND | Missing detail, needs more context | | CONDENSE | Verbose sections, redundancy | | REPHRASE | Awkward phrasing, better alternatives |

Severity levels

| Severity | When to use | |----------|-------------| | must-fix | Blocks publishing — errors, misleading content | | should-fix | Noticeably weak — readers would stumble | | consider | Minor polish — optional improvements |

Agent response actions

| Action | Description | Quill behavior | |--------|-------------|----------------| | resolve | Mark as addressed | Shows green checkmark badge | | clarify | Ask the user a question | Shows orange question badge | | suggest | Propose replacement text | Shows blue suggestion with diff preview | | reject | Explain disagreement | Shows red explanation badge |

Creating annotations (agent-side)

When annotating a document without Quill app:

1. Read the full document to understand context
2. Identify issues with specific character offsets
3. Write actionable comments — what's wrong AND how to fix it
4. Assign category and severity
5. Call quill_add_annotation for each issue
6. Export to ~/.quill/document.json

Comment quality

| Bad | Good | |-----|------| | "Fix this" | "Replace 'utilize' with 'use' — simpler is better" | | "Awkward" | "Split this 45-word sentence into two. Break at 'however'" | | "AI-sounding" | "'Important to note' is filler. Delete or lead with the actual point" |

Export format

~/.quill/document.json:

{
  "filepath": "/path/to/source.md",
  "filename": "source.md",
  "title": "Document Title",
  "content": "Full document text...",
  "wordCount": 450,
  "annotations": [...],
  "preservedFacts": ["238 session transcripts", "126 custom skills"],
  "prompt": "Generated revision prompt..."
}

~/.quill/agent-response.json (written by MCP server):

{
  "version": 1,
  "annotationResponses": [
    {
      "annotationId": "abc-123",
      "action": "suggest",
      "message": "Replaced generic opener",
      "suggestedText": "After six months...",
      "timestamp": "2026-02-05T..."
    }
  ],
  "documentUpdates": [
    {
      "content": "...full revised text...",
      "summary": "Addressed 4 annotations",
      "addressedAnnotationIds": ["abc-123", ...],
      "timestamp": "2026-02-05T..."
    }
  ],
  "lastUpdated": "2026-02-05T..."
}

Integration with other skills

compound-writing (humanization)

# Diagnose AI tells and export annotations
/compound-writing diagnose

# Review in Quill (adjust, resolve false positives)
# Then let agent revise via MCP
/quill revise

writing-editor (style review)

Agent can read the document via MCP, add annotations for style issues, and push fixes — all without manual copy-paste.

MCP setup

Claude Code

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "quill": {
      "command": "node",
      "args": ["~/quill-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "quill": {
    "command": "node",
    "args": ["~/quill-mcp/dist/index.js"]
  }
}

No API keys needed. The MCP server reads/writes ~/.quill/ directly.

Installation

# Build the MCP server
cd ~/quill-mcp
npm install && npm run build

# Build the macOS app (optional, if updating from source)
cd ~/quill && swift build

# Install quill-tui (optional)
cargo install --git https://github.com/szoloth/quill-tui