openwriter 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Travis Steward
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# OpenWriter
+
+**The open-source writing surface for the agentic era.**
+
+A 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.
+
+![OpenWriter — agent writes, you review](https://raw.githubusercontent.com/travsteward/openwriter/main/assets/screenshot.png)
+
+---
+
+## Why OpenWriter?
+
+Claude 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.
+
+Every 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.
+
+Markdown 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.
+
+**The agent writes. You accept or reject. That's it.**
+
+- Documents are plain `.md` files — open existing ones or create new ones
+- Agent makes changes → they appear as colored decorations (green for inserts, blue for rewrites, red for deletions)
+- You review with vim-style hotkeys (`j`/`k` navigate, `a` accept, `r` reject)
+- Cross-document navigation when an agent edits multiple files at once
+- Works with any MCP agent — no vendor lock-in
+
+---
+
+## Quick Start
+
+```bash
+npx openwriter
+```
+
+That's it. Opens your browser to `localhost:5050` with a ready-to-use editor. Documents save as markdown files in `~/.openwriter/`.
+
+Already 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.
+
+### Connect Your Agent
+
+**Claude Code:**
+```bash
+claude mcp add -s user open-writer -- npx openwriter --no-open
+
+# Optional: install the companion skill for better agent behavior
+npx openwriter install-skill
+```
+
+The skill installs a `SKILL.md` to `~/.claude/skills/openwriter/` that teaches Claude Code how to use OpenWriter's 24 tools effectively — writing strategy, review etiquette, and troubleshooting.
+
+**Other MCP agents** (Cursor, OpenCode, etc.) — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "open-writer": {
+      "command": "npx",
+      "args": ["openwriter", "--no-open"]
+    }
+  }
+}
+```
+
+Now your agent has 24 tools to read, write, and organize documents — and every change goes through your review.
+
+---
+
+## Features
+
+### Agent Collaboration via MCP
+
+24 tools across four categories:
+
+| Category | Tools | What They Do |
+|----------|-------|-------------|
+| **Document** | `read_pad`, `write_to_pad`, `edit_text`, `get_pad_status`, + 5 more | Read/write document content, fine-grained text edits, metadata |
+| **Multi-doc** | `list_documents`, `switch_document`, `create_document` | Navigate and manage multiple documents |
+| **Workspace** | `create_workspace`, `get_workspace_structure`, `add_doc`, + 6 more | Organize docs into projects with containers and tags |
+| **Import** | `import_gdoc` | Import Google Docs, auto-split into chapters |
+
+Agents write in markdown or TipTap JSON. The server converts, assigns node IDs, and broadcasts changes to your browser in real-time via WebSocket.
+
+### Pending Change Review
+
+The core interaction model. When an agent (or the context menu) makes changes:
+
+- **Inserts** appear highlighted in green
+- **Rewrites** appear highlighted in blue (original content preserved for reject)
+- **Deletions** appear with red strikethrough
+
+Review Panel (floating bottom bar):
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Next / previous change |
+| `h` / `l` | Previous / next document with changes |
+| `a` | Accept current change |
+| `r` | Reject current change |
+| `Shift+A` | Accept all in document |
+| `Shift+R` | Reject all in document |
+
+### Multi-Document Workspaces
+
+Documents 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.
+
+Four sidebar views:
+- **Tree** — Hierarchical folders with drag-and-drop
+- **Timeline** — Sorted by last modified
+- **Board** — Card-based drill-down navigation
+- **Shelf** — Visual bookshelf metaphor with spine browsing
+
+### Context Menu (Right-Click)
+
+Select text and right-click for AI-powered transformations:
+
+| Action | Key | Description |
+|--------|-----|-------------|
+| Rewrite | `R` | Rewrite selection at similar length |
+| Shrink | `S` | Condense by 40-60% |
+| Expand | `E` | Expand by 50-100% |
+| Custom | — | Free-text instruction |
+| Fill | `F` | Generate content between paragraphs |
+| Insert after | `I` | Generate new content after selection |
+| Delete | `D` | Mark for deletion |
+| Link to doc | `L` | Create internal document links |
+
+Context menu actions are provided by plugins. The built-in [Author's Voice](https://authors-voice.com) plugin rewrites text in your personal writing voice.
+
+### Themes
+
+5 themes, each with light and dark modes:
+
+- **Ink** — Clean, minimal, professional
+- **Novel** — Warm, serif-based, literary
+- **Mono** — Monospace, code-focused
+- **Editorial** — Bold magazine-style headings
+- **Studio** — Contemporary sans-serif
+
+Three typography presets (default, compact, expanded) work with any theme.
+
+### Git Sync
+
+Push your documents to GitHub directly from the editor. Three setup methods:
+- **GitHub CLI** — Auto-detected if `gh` is authenticated
+- **Personal Access Token** — Manual GitHub auth
+- **Existing repo** — Connect to a repo you already have
+
+### Export
+
+Export any document to:
+- Markdown (`.md`)
+- HTML (styled web page)
+- Word (`.docx`)
+- Plain text (`.txt`)
+- PDF (via print preview)
+
+### Version History
+
+Automatic snapshots with full rollback. Browse previous versions and restore any point.
+
+---
+
+## Markdown Native
+
+Every 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.
+
+```
+~/.openwriter/
+├── Getting Started.md
+├── Chapter 1 - Origins.md
+├── Research Notes.md
+└── _workspaces/
+    └── My Novel.json
+```
+
+- **No database.** The filesystem is the index. Move, copy, or `grep` your files however you want.
+- **Open any `.md` file.** Point OpenWriter at existing markdown from any project — it loads instantly.
+- **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.
+- **Frontmatter metadata.** YAML frontmatter for tags, status, or any key-value pairs your workflow needs.
+- **Full markdown fidelity.** Bold, italic, strikethrough, code blocks with syntax highlighting, tables, task lists, images, links, subscript, superscript — all round-trip cleanly to `.md`.
+- **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.
+
+---
+
+## Token-Efficient Wire Format
+
+Agents don't parse JSON. OpenWriter uses a compact tagged-line format that's ~10x more token-efficient:
+
+```
+title: My Document
+words: 1,205
+pending: 2
+---
+[h1:a1b2c3d4] Chapter One
+[p:e5f6g7h8] The quick brown fox jumped over the **lazy** dog.
+[ul:i9j0k1l2]
+  [li:m3n4o5p6] First bullet
+  [li:q7r8s9t0] Second bullet
+```
+
+Each line: `[type:8-char-id] content` with inline markdown preserved. Agents read and write naturally.
+
+---
+
+## Plugin System
+
+OpenWriter is extensible via plugins. A plugin can:
+
+- **Register MCP tools** — Extend the agent's capabilities
+- **Add HTTP routes** — Custom API endpoints on the server
+- **Contribute context menu items** — UI actions for text transformation
+
+```typescript
+import type { OpenWriterPlugin } from 'openwriter';
+
+const plugin: OpenWriterPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  mcpTools(config) {
+    return [{
+      name: 'my-tool',
+      description: 'Does something useful',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async (params) => ({ result: 'done' })
+    }];
+  },
+
+  contextMenuItems() {
+    return [{
+      label: 'My Action',
+      action: 'myplugin:do-thing',
+      condition: 'has-selection'
+    }];
+  }
+};
+
+export default plugin;
+```
+
+Load plugins at startup:
+
+```bash
+npx openwriter --plugins my-plugin,another-plugin
+```
+
+---
+
+## CLI Options
+
+```bash
+npx openwriter [options]
+
+Options:
+  --port <number>       Port number (default: 5050)
+  --no-open             Don't auto-open browser
+  --api-key <key>       Author's Voice API key
+  --av-url <url>        Author's Voice backend URL
+  --plugins <names>     Comma-separated plugin names
+
+Subcommands:
+  install-skill         Install Claude Code companion skill to ~/.claude/skills/openwriter/
+```
+
+Environment variables: `AV_API_KEY`, `AV_BACKEND_URL`
+
+---
+
+## Architecture
+
+```
+Browser (localhost:5050)
+  ├── TipTap 3.0 Editor (React)
+  ├── Decoration Plugin (pending insert/rewrite/delete)
+  ├── Review Panel (accept/reject with keyboard nav)
+  ├── Sidebar (4 views: tree, timeline, board, shelf)
+  └── Context Menu (plugin-provided AI actions)
+         │
+         │ WebSocket + HTTP
+         ▼
+Pad Server (Express + WebSocket + MCP stdio)
+  ├── Document state (in-memory + markdown on disk)
+  ├── 24 MCP tools + plugin tools
+  ├── Workspace management
+  ├── Git sync, versions, export
+  └── Plugin loader
+         │
+         │ MCP stdio
+         ▼
+AI Agent (Claude Code, Cursor, etc.)
+```
+
+Three interfaces:
+- **HTTP** — Browser UI operations, document CRUD, plugin proxying
+- **WebSocket** — Real-time push of agent changes to browser
+- **MCP stdio** — Agent reads/writes documents
+
+The 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.
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/travsteward/openwriter.git
+cd openwriter
+npm install
+
+# Dev mode (hot reload)
+cd packages/openwriter
+npm run dev
+
+# Build
+npx turbo run build --force
+
+# Type check
+npx tsc --noEmit -p packages/openwriter/tsconfig.json        # frontend
+npx tsc --noEmit -p packages/openwriter/tsconfig.server.json  # server
+
+# Run production build
+node packages/openwriter/dist/bin/pad.js
+```
+
+Monorepo structure: `packages/openwriter` (editor + server), `plugins/` (optional extensions).
+
+---
+
+## Contributing
+
+Contributions welcome. Please open an issue first to discuss what you'd like to change.
+
+---
+
+## License
+
+[MIT](LICENSE) — Travis Steward

package/dist/bin/pad.js

@@ -16,49 +16,55 @@ console.log = (...args) => console.error(...args);
 import { startServer } from '../server/index.js';
 import { readConfig, saveConfig } from '../server/helpers.js';
 const args = process.argv.slice(2);
-let port = 5050;
-let noOpen = false;
-let cliApiKey;
-let cliAvUrl;
-let plugins = [];
-for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--port' && args[i + 1]) {
-        port = parseInt(args[i + 1], 10);
-        i++;
-    }
-    if (args[i] === '--no-open') {
-        noOpen = true;
-    }
-    if (args[i] === '--api-key' && args[i + 1]) {
-        cliApiKey = args[i + 1];
-        i++;
-    }
-    if (args[i] === '--av-url' && args[i + 1]) {
-        cliAvUrl = args[i + 1];
-        i++;
+// Subcommands (run and exit, don't start server)
+if (args[0] === 'install-skill') {
+    import('../server/install-skill.js').then(m => m.installSkill());
+}
+else {
+    let port = 5050;
+    let noOpen = false;
+    let cliApiKey;
+    let cliAvUrl;
+    let plugins = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--port' && args[i + 1]) {
+            port = parseInt(args[i + 1], 10);
+            i++;
+        }
+        if (args[i] === '--no-open') {
+            noOpen = true;
+        }
+        if (args[i] === '--api-key' && args[i + 1]) {
+            cliApiKey = args[i + 1];
+            i++;
+        }
+        if (args[i] === '--av-url' && args[i + 1]) {
+            cliAvUrl = args[i + 1];
+            i++;
+        }
+        if (args[i] === '--plugins' && args[i + 1]) {
+            plugins = args[i + 1].split(',').map((s) => s.trim()).filter(Boolean);
+            i++;
+        }
     }
-    if (args[i] === '--plugins' && args[i + 1]) {
-        plugins = args[i + 1].split(',').map((s) => s.trim()).filter(Boolean);
-        i++;
+    // Resolve API key: CLI flag → env var → saved config
+    const config = readConfig();
+    const avApiKey = cliApiKey || process.env.AV_API_KEY || config.avApiKey || '';
+    const avBackendUrl = cliAvUrl || process.env.AV_BACKEND_URL || config.avBackendUrl;
+    // Persist new values to config so future starts don't need them
+    const updates = {};
+    if (cliApiKey && cliApiKey !== config.avApiKey)
+        updates.avApiKey = cliApiKey;
+    if (cliAvUrl && cliAvUrl !== config.avBackendUrl)
+        updates.avBackendUrl = cliAvUrl;
+    if (Object.keys(updates).length > 0) {
+        saveConfig(updates);
+        console.log('Config saved to ~/.openwriter/config.json');
     }
+    // Set env vars for downstream code (plugins read process.env)
+    if (avApiKey)
+        process.env.AV_API_KEY = avApiKey;
+    if (avBackendUrl)
+        process.env.AV_BACKEND_URL = avBackendUrl;
+    startServer({ port, noOpen, plugins });
 }
-// Resolve API key: CLI flag → env var → saved config
-const config = readConfig();
-const avApiKey = cliApiKey || process.env.AV_API_KEY || config.avApiKey || '';
-const avBackendUrl = cliAvUrl || process.env.AV_BACKEND_URL || config.avBackendUrl;
-// Persist new values to config so future starts don't need them
-const updates = {};
-if (cliApiKey && cliApiKey !== config.avApiKey)
-    updates.avApiKey = cliApiKey;
-if (cliAvUrl && cliAvUrl !== config.avBackendUrl)
-    updates.avBackendUrl = cliAvUrl;
-if (Object.keys(updates).length > 0) {
-    saveConfig(updates);
-    console.log('Config saved to ~/.openwriter/config.json');
-}
-// Set env vars for downstream code (plugins read process.env)
-if (avApiKey)
-    process.env.AV_API_KEY = avApiKey;
-if (avBackendUrl)
-    process.env.AV_BACKEND_URL = avBackendUrl;
-startServer({ port, noOpen, plugins });

package/dist/server/install-skill.js

@@ -0,0 +1,19 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function installSkill() {
+    const source = path.join(__dirname, '../../skill/SKILL.md');
+    const targetDir = path.join(os.homedir(), '.claude', 'skills', 'openwriter');
+    const target = path.join(targetDir, 'SKILL.md');
+    if (!fs.existsSync(source)) {
+        console.error(`Error: SKILL.md not found at ${source}`);
+        process.exit(1);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.copyFileSync(source, target);
+    console.error(`Installed OpenWriter skill to ${target}`);
+    process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local TipTap editor for human-agent collaboration via MCP",
   "type": "module",
   "license": "MIT",
@@ -83,6 +83,7 @@
   },
   "files": [
     "dist/",
+    "skill/",
     "package.json"
   ]
 }

package/skill/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: openwriter
+description: |
+  OpenWriter — local TipTap editor for human-agent collaboration.
+  Agent reads/edits documents via MCP tools (read_pad, write_to_pad, etc.).
+  Changes appear as pending decorations the user accepts or rejects.
+  Multi-document workspace with sidebar navigation.
+
+  Use when user says: "open writer", "openwriter", "write in openwriter",
+  "edit my document", "review my writing", "check the pad".
+
+  Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
+---
+
+# OpenWriter — Public Companion Skill
+
+You are a writing collaborator. The user has a document open in OpenWriter (http://localhost:5050). You read their document and make edits **exclusively via MCP tools**. Edits appear as pending decorations (colored highlights) that the user can accept or reject.
+
+**First action when activated:** Always share the browser URL:
+> OpenWriter is at **http://localhost:5050**
+
+## Quick Setup
+
+OpenWriter must be configured as an MCP server before use. Two paths:
+
+### Option A: User runs it from their terminal (outside Claude Code)
+
+```bash
+claude mcp add -s user open-writer -- npx openwriter --no-open
+```
+
+Then restart the Claude Code session. The MCP tools become available automatically.
+
+### Option B: Agent configures it (when user asks you to set it up)
+
+Edit `~/.claude.json` and add to the `mcpServers` object:
+
+```json
+"open-writer": {
+  "command": "npx",
+  "args": ["openwriter", "--no-open"]
+}
+```
+
+The `mcpServers` key is at the top level of `~/.claude.json`. If it doesn't exist, create it. Example:
+
+```json
+{
+  "mcpServers": {
+    "open-writer": {
+      "command": "npx",
+      "args": ["openwriter", "--no-open"]
+    }
+  }
+}
+```
+
+After editing, tell the user:
+1. Restart your Claude Code session (the MCP server loads on startup)
+2. Open http://localhost:5050 in your browser
+
+**Note:** You cannot run `claude mcp add` from inside a session (nested session error). That's why we edit the JSON directly.
+
+## MCP Tools Reference (24 tools)
+
+### Document Operations
+
+| Tool | Description |
+|------|-------------|
+| `read_pad` | Read the current document (compact tagged-line format) |
+| `write_to_pad` | Apply edits as pending decorations (rewrite, insert, delete) |
+| `get_pad_status` | Lightweight poll: word count, pending changes, userSignaledReview |
+| `get_nodes` | Fetch specific nodes by ID |
+| `get_metadata` | Get frontmatter metadata for the active document |
+| `set_metadata` | Update frontmatter metadata (merge, set key to null to remove) |
+
+### Document Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `list_documents` | List all documents with filename, word count, active status |
+| `switch_document` | Switch to a different document by filename |
+| `create_document` | Create a new document (optional title, content, path) |
+| `open_file` | Open an existing .md file from any location on disk |
+
+### Import
+
+| Tool | Description |
+|------|-------------|
+| `replace_document` | Import external content into a new/blank document |
+| `import_gdoc` | Import a Google Doc (auto-splits multi-chapter docs) |
+
+### Workspace Management
+
+| Tool | Description |
+|------|-------------|
+| `list_workspaces` | List all workspaces with title and doc count |
+| `create_workspace` | Create a new workspace |
+| `get_workspace_structure` | Get full workspace tree: containers, docs, tags, context |
+| `get_item_context` | Get progressive disclosure context for a doc in a workspace |
+| `update_workspace_context` | Update workspace context (characters, settings, rules) |
+
+### Workspace Organization
+
+| Tool | Description |
+|------|-------------|
+| `add_doc` | Add a document to a workspace (optional container placement) |
+| `create_container` | Create a folder inside a workspace (max depth: 3) |
+| `tag_doc` | Add a tag to a document in a workspace |
+| `untag_doc` | Remove a tag from a document |
+| `move_doc` | Move a document to a different container or root level |
+
+### Text Operations
+
+| Tool | Description |
+|------|-------------|
+| `edit_text` | Fine-grained text edits within a node (find/replace, add/remove marks) |
+
+## Writing Strategy
+
+**Incremental edits, not monolithic replacement.**
+
+- Use `write_to_pad` for all edits — never `replace_document` (unless importing into a blank doc)
+- Send **3-8 changes per call** for a responsive, streaming feel
+- Always `read_pad` before writing — you need fresh node IDs
+- Respect `pendingChanges > 0` — wait for the user to accept/reject before sending more
+- Content accepts markdown strings (preferred) or TipTap JSON
+- Decoration colors: **blue** = rewrite, **green** = insert, **red** = delete
+
+## Workflow
+
+### Single document
+
+```
+1. get_pad_status  → check pendingChanges and userSignaledReview
+2. read_pad        → get full document with node IDs
+3. write_to_pad    → send changes (3-8 per call)
+4. Wait            → user accepts/rejects in browser
+```
+
+### Multi-document
+
+```
+1. list_documents    → see all docs, find target
+2. switch_document   → save current, load target (returns content)
+3. read_pad          → read full content with node IDs
+4. write_to_pad      → apply edits
+```
+
+### Creating new content
+
+```
+1. create_document({ title: "My Doc", content: "# Heading\n\nContent..." })
+2. read_pad          → get node IDs from created content
+3. write_to_pad      → refine with edits
+```
+
+## Review Etiquette
+
+1. **Share the URL.** Always tell the user: http://localhost:5050
+2. **Read before writing.** Always fetch the document before suggesting changes
+3. **Don't overwhelm.** 1-3 changes at a time for reviews, 3-8 for drafting
+4. **Explain your edits.** Tell the user what you changed and why
+5. **Respect pending changes.** If `pendingChanges > 0`, wait for the user
+6. **Watch for the review signal.** When `userSignaledReview` is true, the user is asking for your input — reading status clears it (one-shot)
+
+## Troubleshooting
+
+**MCP tools not available** — Run `/mcp` in Claude Code to check connection status. Click reconnect if needed.
+
+**Port 5050 busy** — Another OpenWriter instance owns the port. New sessions auto-enter client mode (proxying via HTTP) — tools still work. No action needed.
+
+**Edits don't appear** — Stale node IDs. Always `read_pad` before `write_to_pad` to get fresh IDs.
+
+**"pendingChanges" never clears** — User needs to accept/reject changes in the browser at http://localhost:5050.
+
+**Server not starting** — Ensure `npx openwriter` works from your terminal. If on Windows and using `npx`, the MCP config may need `"command": "cmd"` with `"args": ["/c", "npx", "openwriter", "--no-open"]`.