# OpenWriter — Full Documentation for AI Agents

> **Agent discovery note:** Every page on https://openwriter.io is also available as plain markdown. Append `.md` to any URL (e.g. `https://openwriter.io/features.md`), or send `Accept: text/markdown` to the original URL — the server returns markdown via content negotiation. This file is the long-form complete documentation in a single fetchable artifact.

## What OpenWriter Is

OpenWriter is an open-source (MIT) markdown-native rich text editor with first-class AI agent collaboration via Model Context Protocol (MCP). The agent drafts, the human accepts or rejects every change with a single keystroke, and the work ships to any publishing surface — X, blog, newsletter, schedule queue — from the same pad.

Plain `.md` files on disk. No database. No lock-in. Your writing is yours.

## How It Works

The architecture is built around three layers that stay decoupled:

**Layer 1 — Editor.** TipTap 3.0 under the hood. Full rich-text formatting with markdown-native storage. Every keystroke writes to a `.md` file on disk with YAML frontmatter for metadata. Headings, lists, blockquotes, code blocks, tables, links, images, blockquotes — everything you need. Markdown shortcuts work inline.

**Layer 2 — Agent collaboration via MCP.** OpenWriter ships an MCP server exposing 61 tools that cover documents (create/read/edit/delete/version), workspaces (multi-doc containers), publishing (X, blog, newsletter), scheduling, image generation, and the author's voice profile. Compatible with any MCP-aware agent: Claude Code, Codex CLI, OpenCode, Cursor, Windsurf, GitHub Copilot, VS Code, Zed. The agent reads your pad, proposes edits, and the edits arrive as *pending changes* — colored decorations in the editor (green for inserts, blue for rewrites, red for deletes) that you accept or reject with single keystrokes.

**Layer 3 — Publishing.** When a document is ready, ship it directly from the pad. X tweets, X threads, and X articles via the X compose views. Newsletter via SendGrid with your own domain (no Substack cut). Blog via the GitHub plugin to any static site. Scheduler queues posts across all platforms.

## Key Features

### Editor

- **TipTap 3.0 rich text editor** with markdown-native storage
- **Full formatting** — headings (H1-H6), lists, blockquotes, code blocks (fenced), tables, links, images, inline formatting (bold, italic, code, strikethrough)
- **Markdown shortcuts** — type `# ` for heading, `- ` for list, `> ` for quote, `\`\`\`` for code block, all inline
- **Pending change review** — agent edits appear as colored decorations. Navigate with `j`/`k`, accept with `a`, reject with `r`, accept all with `Shift+A`
- **Workspaces** — sidebar tree of documents grouped into containers (workspaces). Nest documents inside workspaces (e.g. a book has chapters; a newsletter has issues)
- **Versioning** — every save is a version; restore any prior version
- **Export** — HTML, DOCX, PDF
- **Image generation** — Google Gemini image generation for cover images and inline illustrations

### AI Collaboration (61 MCP Tools)

The MCP server exposes 61 tools organized by surface:

- **Document tools**: `create_document`, `read_pad`, `edit_text`, `delete_document`, `archive_document`, `unarchive_document`, `outline_doc`, `peek_doc`, `populate_document`, `naturalize_slots`, `rename_item`, `move_item`, `switch_document`
- **Workspace tools**: `create_workspace`, `delete_workspace`, `list_workspaces`, `get_workspace_structure`, `update_workspace_context`, `create_container`, `delete_container`, `list_documents`, `browse_docs`, `search_docs`
- **Editing tools**: `create_slot`, `edit_slot`, `delete_slot`, `list_slots`, `get_item_context`, `get_nodes`, `link_to`
- **Versioning + state**: `list_versions`, `restore_version`, `create_checkpoint`, `declare_writes`, `reload_from_disk`, `get_pad_status`
- **Agent collaboration**: `get_agent_marks`, `resolve_agent_marks`, `get_comments`, `resolve_comments`, `propose_sort`, `mark_sorted`, `list_pending_sorts`
- **Tagging + metadata**: `tag_doc`, `untag_doc`, `set_metadata`, `get_metadata`, `mark_enriched`, `list_dirty_docs`
- **Publishing**: `post_to_x`, `post_to_linkedin`, `post_to_blog`, `add_blog_site`, `list_blog_sites`, `remove_blog_site`, `inspect_blog_repo`, `schedule_post`, `list_schedule`, `manage_schedule`
- **Newsletter**: `add_subscriber`, `import_subscribers`, `list_subscribers`, `send_newsletter`, `list_newsletter_issues`, `get_newsletter_analytics`, `resend_to_unopened`, `get_subscribe_embed`
- **Domain + billing**: `setup_custom_domain`, `check_domain_status`, `resend_domain_verification`, `manage_billing`, `get_billing`, `upgrade_plan`
- **Imports + sync**: `import_gdoc`, `crawl`, `open_file`, `insert_image`, `get_graph`, `get_doc_link`, `list_connections`
- **Misc**: `add_task`, `list_tasks`, `update_task`, `remove_task`, `manage_autoplugs`, `list_autoplug_tracking`, `request_login_code`, `verify_login`

Every tool is documented in the MCP schema; agents discover capabilities at runtime.

### Compose Views

Five compose modes, each with view-specific UI tuned to the destination platform:

- **Standard pad** — default writing surface
- **X tweet/thread** — pixel-accurate X UI for drafting replies, quote tweets, threads. Character counter, media attachment, thread builder
- **X article** — full-bleed long-form article with cover image (X's article format)
- **Newsletter** — four-layout email editor (single column, two column, hero+body, image-first) with inline image generation
- **Book** — long-form / multi-chapter view with chapter tree, scene break support, vignette library, beat-map architecture

### Publishing

- **X (Twitter)** — direct posting via X API v2. Tweets, threads, quote tweets, articles. Pixel-accurate preview before sending
- **Blog (GitHub plugin)** — `post_to_blog` writes Markdown to any static site (Astro, Hugo, Jekyll, etc.) via a configured GitHub repo. Title, slug, OG description, featured image all auto-populated
- **Newsletter** — SendGrid-powered delivery with your own domain (custom domain verification + DKIM via the OpenWriter dashboard). Four layouts. Draft, preview, send from the same editor. No middleman taking a cut
- **Schedule queue** — `schedule_post` queues any of the above for future delivery. View, edit, cancel from `list_schedule`

### Author's Voice

OpenWriter's author's-voice plugin is the constructed-voice anchoring system. It builds a profile from the author's existing corpus, anchors prose generation to a blend of training-data authors, layers NEVER rules and presentation fingerprints, and progressively tightens with curated examples. The result: AI drafts that sound like the human, not generic LLM register.

## Install

```bash
npx openwriter setup
```

One command:
1. Installs the OpenWriter CLI globally
2. Configures the MCP server for your agent (Claude Code, Cursor, etc.)
3. Opens the editor at `localhost:5050`

Restart your agent, then type `/openwriter` (Claude Code) or invoke the OpenWriter tools (any MCP-aware agent) to start writing.

## Pricing

Open source under MIT. The editor and MCP server are free forever. Hosted publishing surfaces (custom-domain newsletter, scheduled publishing) are available on the OpenWriter cloud plan; see https://openwriter.io/ for current pricing or self-host everything.

## Use Cases

- **Newsletter writing**: write the weekly issue, generate the cover image, send to subscribers — same editor, no platform tax
- **Book writing**: scaffold a book with chapters and parts, use the agent to draft scene-by-scene, accept changes inline, export to manuscript format
- **X content pipeline**: brainstorm, draft, polish, schedule X threads and articles. Pixel-accurate preview, no surprises on publish
- **Blog post pipeline**: write in the pad, agent suggests improvements, push to GitHub via the blog plugin — your static site updates automatically
- **Documentation**: write docs in the editor, agent fills gaps, publish to the doc site

## Trust & Security

- **Plain markdown on disk** — no proprietary format. If OpenWriter shuts down tomorrow, your writing is `.md` files in a folder. Open them in any editor.
- **MIT license** — fork it, modify it, self-host it. No usage restrictions.
- **MCP protocol** — open standard from Anthropic. Your agent doesn't need OpenWriter-specific support; it just needs MCP, which every major AI agent now supports.
- **Local-first** — the editor runs on `localhost:5050`. Your drafts never leave your machine unless you explicitly publish them.

## Technical Details

- **Frontend**: TipTap 3.0 editor, React, Vite
- **Backend**: Node + WebSocket sync between editor and MCP server
- **Storage**: plain `.md` files with YAML frontmatter; no database
- **MCP integration**: stdio + WebSocket transports
- **Newsletter**: SendGrid + domain verification (SPF, DKIM, DMARC)
- **Publishing**: X API v2, GitHub API (for blog plugin), SendGrid (for newsletter)
- **Image generation**: Google Gemini

## Repository

- GitHub: https://github.com/travsteward/openwriter
- Issues + feature requests: https://github.com/travsteward/openwriter/issues
- License: MIT