openwriter 0.1.0 → 0.1.1

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,297 @@
+# OpenWriter
+
+**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.
+
+<!-- TODO: Add screenshot or GIF demo here -->
+
+---
+
+## Why OpenWriter?
+
+Every AI coding tool has a great editor. Writing has nothing.
+
+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.
+
+**The agent writes. You accept or reject. That's it.**
+
+- 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/`.
+
+### Connect Your Agent
+
+Add to your MCP config (e.g., `.claude/mcp.json`):
+
+```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.
+
+---
+
+## 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
+```
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local TipTap editor for human-agent collaboration via MCP",
   "type": "module",
   "license": "MIT",