openwriter 0.1.1 → 0.2.0

package/README.md

@@ -2,20 +2,23 @@
 
 **The open-source writing surface for the agentic era.**
 
-A local-first [TipTap](https://tiptap.dev/) rich text editor built for human-agent collaboration. Your AI agent writes, you review. Works with any MCP-compatible agent — Claude Code, Cursor, OpenCode, or your own.
+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.
 
-<!-- TODO: Add screenshot or GIF demo here -->
+![OpenWriter — agent writes, you review](https://raw.githubusercontent.com/travsteward/openwriter/main/assets/screenshot.png)
 
 ---
 
 ## Why OpenWriter?
 
-Every AI coding tool has a great editor. Writing has nothing.
+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.
 
-Google Docs locks you into Gemini. Notion locks you into Notion AI. Obsidian has plugins but no native agent protocol. OpenWriter is different: it's an open editor that any agent can write into, with a review system that keeps you in control.
+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
@@ -31,9 +34,21 @@ 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
 
-Add to your MCP config (e.g., `.claude/mcp.json`):
+**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
 {
@@ -145,6 +160,28 @@ Automatic snapshots with full rollback. Browse previous versions and restore any
 
 ---
 
+## 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:
@@ -220,6 +257,9 @@ Options:
   --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`

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.1",
+  "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"]`.