{"id":48752137,"url":"https://github.com/travsteward/openwriter","last_synced_at":"2026-05-23T19:01:39.635Z","repository":{"id":339046542,"uuid":"1160196984","full_name":"travsteward/openwriter","owner":"travsteward","description":"The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.","archived":false,"fork":false,"pushed_at":"2026-05-21T05:03:05.000Z","size":4069,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T08:57:02.415Z","etag":null,"topics":["ai","ai-agents","ai-writing","anthropic","claude","claude-code","claude-skills","collaborative-editing","content-creation","editor","markdown","mcp","model-context-protocol","newsletter","open-source","publishing","tiptap","writing","writing-tools"],"latest_commit_sha":null,"homepage":"https://openwriter.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/travsteward.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T16:50:36.000Z","updated_at":"2026-05-21T05:03:09.000Z","dependencies_parsed_at":"2026-04-03T17:03:12.460Z","dependency_job_id":null,"html_url":"https://github.com/travsteward/openwriter","commit_stats":null,"previous_names":["travsteward/openwriter"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/travsteward/openwriter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travsteward%2Fopenwriter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travsteward%2Fopenwriter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travsteward%2Fopenwriter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travsteward%2Fopenwriter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travsteward","download_url":"https://codeload.github.com/travsteward/openwriter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travsteward%2Fopenwriter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-writing","anthropic","claude","claude-code","claude-skills","collaborative-editing","content-creation","editor","markdown","mcp","model-context-protocol","newsletter","open-source","publishing","tiptap","writing","writing-tools"],"created_at":"2026-04-12T20:03:43.530Z","updated_at":"2026-05-23T19:01:39.628Z","avatar_url":"https://github.com/travsteward.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenWriter\r\n\r\n**The open-source writing surface for the agentic era.**\r\n\r\nA markdown-native rich text editor built for human-agent collaboration. Your AI agent writes, you review. Plain `.md` files on disk — no database, no lock-in. Works with any MCP-compatible agent.\r\n\r\n![OpenWriter — agent writes, you review](assets/screenshot.png)\r\n\r\n---\r\n\r\n## Why OpenWriter?\r\n\r\nClaude Code, OpenCode, Codex — these agents are transforming how people build software. But that power hasn't crossed over to writing. Ask an agent to edit your essay and you're staring at raw markdown in a terminal. There's no collaborative surface, no way to review changes, no real workflow.\r\n\r\nEvery writing tool is racing to bolt on its own weak agent. They have it backwards. The most powerful agents already exist — and they're designed to work with tools, not be trapped inside one. OpenWriter doesn't ship an agent. It's the first writing surface built for the agents you already use, with a review system that keeps you in control.\r\n\r\nMarkdown is the native language of AI. Every LLM reads it, writes it, and thinks in it. OpenWriter treats `.md` files as first-class citizens — your documents are plain markdown on disk, and the editor adds rich formatting, workspaces, version history, and agent collaboration on top. No proprietary format. No database. Just files.\r\n\r\n**The agent writes. You accept or reject. That's it.**\r\n\r\n- Documents are plain `.md` files — open existing ones or create new ones\r\n- Agent makes changes → they appear as colored decorations (green for inserts, blue for rewrites, red for deletions)\r\n- You review with vim-style hotkeys (`j`/`k` navigate, `a` accept, `r` reject)\r\n- Cross-document navigation when an agent edits multiple files at once\r\n- Works with any MCP agent — no vendor lock-in\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install -g openwriter\r\nopenwriter\r\n```\r\n\r\nThat's it. Opens your browser to `localhost:5050` with a ready-to-use editor. Documents save as markdown files in `~/.openwriter/`.\r\n\r\n\u003e **Try without installing:** `npx openwriter` works too, but global install starts instantly (no npm resolution delay on every launch).\r\n\r\nAlready have markdown files? Open them directly — the agent can use `open_file` to load any `.md` from disk, or you can drag files into the sidebar.\r\n\r\n### Connect Your Agent\r\n\r\n**Install the skill** (Claude Code, Cursor, Codex, and 20+ agents):\r\n```bash\r\nnpx skills add https://github.com/travsteward/openwriter --skill openwriter\r\n```\r\n\r\nThen add the MCP server for the 24 editing tools:\r\n```bash\r\nclaude mcp add -s user openwriter -- openwriter --no-open\r\n```\r\n\r\nThe skill teaches your agent how to use OpenWriter's tools effectively — writing strategy, review etiquette, and troubleshooting. The MCP server provides the actual document editing capabilities.\r\n\r\n**Other MCP agents** (Cursor, OpenCode, etc.) — add to your MCP config:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"openwriter\": {\r\n      \"command\": \"openwriter\",\r\n      \"args\": [\"--no-open\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nNow your agent has 24 tools to read, write, and organize documents — and every change goes through your review.\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Agent Collaboration via MCP\r\n\r\n24 tools across four categories:\r\n\r\n| Category | Tools | What They Do |\r\n|----------|-------|-------------|\r\n| **Document** | `read_pad`, `write_to_pad`, `edit_text`, `get_pad_status`, + 5 more | Read/write document content, fine-grained text edits, metadata |\r\n| **Multi-doc** | `list_documents`, `switch_document`, `create_document` | Navigate and manage multiple documents |\r\n| **Workspace** | `create_workspace`, `get_workspace_structure`, `add_doc`, + 6 more | Organize docs into projects with containers and tags |\r\n| **Import** | `import_gdoc` | Import structured Google Docs, auto-split into chapters |\r\n\r\nAgents write in markdown or TipTap JSON. The server converts, assigns node IDs, and broadcasts changes to your browser in real-time via WebSocket.\r\n\r\n### Pending Change Review\r\n\r\nThe core interaction model. When an agent (or the context menu) makes changes:\r\n\r\n- **Inserts** appear highlighted in green\r\n- **Rewrites** appear highlighted in blue (original content preserved for reject)\r\n- **Deletions** appear with red strikethrough\r\n\r\nReview Panel (floating bottom bar):\r\n\r\n| Key | Action |\r\n|-----|--------|\r\n| `j` / `k` | Next / previous change |\r\n| `h` / `l` | Previous / next document with changes |\r\n| `a` | Accept current change |\r\n| `r` | Reject current change |\r\n| `Shift+A` | Accept all in document |\r\n| `Shift+R` | Reject all in document |\r\n\r\n### Multi-Document Workspaces\r\n\r\nDocuments are markdown files on disk. Organize them into workspaces with nested containers, cross-cutting tags, and shared context (characters, settings, rules) that agents can read for consistency.\r\n\r\nFour sidebar views:\r\n- **Tree** — Hierarchical folders with drag-and-drop\r\n- **Timeline** — Sorted by last modified\r\n- **Board** — Card-based drill-down navigation\r\n- **Shelf** — Visual bookshelf metaphor with spine browsing\r\n\r\n### Context Menu (Right-Click)\r\n\r\nSelect text and right-click for AI-powered transformations:\r\n\r\n| Action | Key | Description |\r\n|--------|-----|-------------|\r\n| Rewrite | `R` | Rewrite selection at similar length |\r\n| Shrink | `S` | Condense by 40-60% |\r\n| Expand | `E` | Expand by 50-100% |\r\n| Custom | — | Free-text instruction |\r\n| Fill | `F` | Generate content between paragraphs |\r\n| Insert after | `I` | Generate new content after selection |\r\n| Delete | `D` | Mark for deletion |\r\n| Link to doc | `L` | Create internal document links |\r\n\r\nContext menu actions are provided by plugins. The built-in [Author's Voice](https://authors-voice.com) plugin rewrites text in your personal writing voice.\r\n\r\n### Themes\r\n\r\n5 themes, each with light and dark modes:\r\n\r\n- **Ink** — Clean, minimal, professional\r\n- **Novel** — Warm, serif-based, literary\r\n- **Mono** — Monospace, code-focused\r\n- **Editorial** — Bold magazine-style headings\r\n- **Studio** — Contemporary sans-serif\r\n\r\nThree typography presets (default, compact, expanded) work with any theme.\r\n\r\n### Git Sync\r\n\r\nPush your documents to GitHub directly from the editor. Three setup methods:\r\n- **GitHub CLI** — Auto-detected if `gh` is authenticated\r\n- **Personal Access Token** — Manual GitHub auth\r\n- **Existing repo** — Connect to a repo you already have\r\n\r\n### Export\r\n\r\nExport any document to:\r\n- Markdown (`.md`)\r\n- HTML (styled web page)\r\n- Word (`.docx`)\r\n- Plain text (`.txt`)\r\n- PDF (via print preview)\r\n\r\n### Version History\r\n\r\nAutomatic snapshots with full rollback. Browse previous versions and restore any point.\r\n\r\n---\r\n\r\n## Markdown Native\r\n\r\nEvery document is a `.md` file on disk. What you see in the editor is markdown with rich rendering — headings, lists, tables, code blocks, images, links — all stored as plain text.\r\n\r\n```\r\n~/.openwriter/\r\n├── Getting Started.md\r\n├── Chapter 1 - Origins.md\r\n├── Research Notes.md\r\n└── _workspaces/\r\n    └── My Novel.json\r\n```\r\n\r\n- **No database.** The filesystem is the index. Move, copy, or `grep` your files however you want.\r\n- **Open any `.md` file.** Point OpenWriter at existing markdown from any project — it loads instantly.\r\n- **Git Sync built in.** Push your documents to GitHub directly from the editor. Your markdown files are version-controlled and portable — access them from any machine or future web client.\r\n- **Frontmatter metadata.** YAML frontmatter for tags, status, or any key-value pairs your workflow needs.\r\n- **Full markdown fidelity.** Bold, italic, strikethrough, code blocks with syntax highlighting, tables, task lists, images, links, subscript, superscript — all round-trip cleanly to `.md`.\r\n- **AI-native format.** Every LLM reads and writes markdown natively. No conversion layer, no token waste. The agent edits the same format the file is stored in.\r\n\r\n---\r\n\r\n## Token-Efficient Wire Format\r\n\r\nAgents don't parse JSON. OpenWriter uses a compact tagged-line format that's ~10x more token-efficient:\r\n\r\n```\r\ntitle: My Document\r\nwords: 1,205\r\npending: 2\r\n---\r\n[h1:a1b2c3d4] Chapter One\r\n[p:e5f6g7h8] The quick brown fox jumped over the **lazy** dog.\r\n[ul:i9j0k1l2]\r\n  [li:m3n4o5p6] First bullet\r\n  [li:q7r8s9t0] Second bullet\r\n```\r\n\r\nEach line: `[type:8-char-id] content` with inline markdown preserved. Agents read and write naturally.\r\n\r\n---\r\n\r\n## Plugin System\r\n\r\nOpenWriter is extensible via plugins. A plugin can:\r\n\r\n- **Register MCP tools** — Extend the agent's capabilities\r\n- **Add HTTP routes** — Custom API endpoints on the server\r\n- **Contribute context menu items** — UI actions for text transformation\r\n\r\n```typescript\r\nimport type { OpenWriterPlugin } from 'openwriter';\r\n\r\nconst plugin: OpenWriterPlugin = {\r\n  name: 'my-plugin',\r\n  version: '1.0.0',\r\n\r\n  mcpTools(config) {\r\n    return [{\r\n      name: 'my-tool',\r\n      description: 'Does something useful',\r\n      inputSchema: { type: 'object', properties: {} },\r\n      handler: async (params) =\u003e ({ result: 'done' })\r\n    }];\r\n  },\r\n\r\n  contextMenuItems() {\r\n    return [{\r\n      label: 'My Action',\r\n      action: 'myplugin:do-thing',\r\n      condition: 'has-selection'\r\n    }];\r\n  }\r\n};\r\n\r\nexport default plugin;\r\n```\r\n\r\nLoad plugins at startup:\r\n\r\n```bash\r\nopenwriter --plugins my-plugin,another-plugin\r\n```\r\n\r\n---\r\n\r\n## CLI Options\r\n\r\n```bash\r\nopenwriter [options]\r\n\r\nOptions:\r\n  --port \u003cnumber\u003e       Port number (default: 5050)\r\n  --no-open             Don't auto-open browser\r\n  --api-key \u003ckey\u003e       Author's Voice API key\r\n  --av-url \u003curl\u003e        Author's Voice backend URL\r\n  --plugins \u003cnames\u003e     Comma-separated plugin names\r\n\r\nSubcommands:\r\n  install-skill         Install Claude Code companion skill to ~/.claude/skills/openwriter/\r\n```\r\n\r\nEnvironment variables: `AV_API_KEY`, `AV_BACKEND_URL`\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n```\r\nBrowser (localhost:5050)\r\n  ├── TipTap 3.0 Editor (React)\r\n  ├── Decoration Plugin (pending insert/rewrite/delete)\r\n  ├── Review Panel (accept/reject with keyboard nav)\r\n  ├── Sidebar (4 views: tree, timeline, board, shelf)\r\n  └── Context Menu (plugin-provided AI actions)\r\n         │\r\n         │ WebSocket + HTTP\r\n         ▼\r\nPad Server (Express + WebSocket + MCP stdio)\r\n  ├── Document state (in-memory + markdown on disk)\r\n  ├── 24 MCP tools + plugin tools\r\n  ├── Workspace management\r\n  ├── Git sync, versions, export\r\n  └── Plugin loader\r\n         │\r\n         │ MCP stdio\r\n         ▼\r\nAI Agent (Claude Code, Cursor, etc.)\r\n```\r\n\r\nThree interfaces:\r\n- **HTTP** — Browser UI operations, document CRUD, plugin proxying\r\n- **WebSocket** — Real-time push of agent changes to browser\r\n- **MCP stdio** — Agent reads/writes documents\r\n\r\nThe server supports **multi-session mode**: if port 5050 is already taken, additional instances proxy MCP calls via HTTP to the running server. Multiple agents can safely share the same document state.\r\n\r\n---\r\n\r\n## Development\r\n\r\n```bash\r\n# Clone and install\r\ngit clone https://github.com/travsteward/openwriter.git\r\ncd openwriter\r\nnpm install\r\n\r\n# Dev mode (hot reload)\r\ncd packages/openwriter\r\nnpm run dev\r\n\r\n# Build\r\nnpx turbo run build --force\r\n\r\n# Type check\r\nnpx tsc --noEmit -p packages/openwriter/tsconfig.json        # frontend\r\nnpx tsc --noEmit -p packages/openwriter/tsconfig.server.json  # server\r\n\r\n# Run production build\r\nnode packages/openwriter/dist/bin/pad.js\r\n```\r\n\r\nMonorepo structure: `packages/openwriter` (editor + server), `plugins/` (optional extensions).\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions welcome. Please open an issue first to discuss what you'd like to change.\r\n\r\n---\r\n\r\n## License\r\n\r\n[MIT](LICENSE) — Travis Steward\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravsteward%2Fopenwriter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravsteward%2Fopenwriter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravsteward%2Fopenwriter/lists"}