cowrite

<h1 align="center">Cowrite</h1> <p align="center"><code>cowrite</code></p> <p align="center"><i>'You say it in the Agent, and the article grows in the browser.'</i></p> <p align="center"> <img alt="Protocol" src="https://img.shields.io/badge/protocol-MCP-6B7280"> <img alt="Bundled skills" src="https://img.shields.io/badge/bundled_skills-8-2563EB"> <img alt="Output" src="https://img.shields.io/badge/output-Markdown%20%7C%20PNG%20%7C%20PPTX%20%7C%20HTML-111827"> <img alt="Runtime" src="https://img.shields.io/badge/runtime-local-16A34A"> </p> <p align="center">MIT · Codex / Claude Code compatible · Contact: Space</p> Cowrite is a locally running conversational writing canvas. The browser is responsible for hosting and editing articles, while Codex / Claude Code reads and writes the same data through MCP; illustrations are uniformly called from Codex's built-in `image_gen`, and HTML interpretation and article optimization are completed by the repository's built-in Skill. It also provides Codex and Claude Code marketplaces, which will automatically prepare dependencies, build the front-end, and start local services after installation. ## Installation Requirements: Node.js 20.19+ (or 22.12+), npm, and a logged-in Codex CLI or Claude Code. Using "Send to Feishu" also requires installing and logging in to `lark-cli` on the local machine, as well as installing its `lark-doc` Skill. ### Let Codex Automatically Install Send the following command to Codex: ```text Please install Cowrite: https://github.com/SpaceZephyr/cowrite.git Please run in sequence: 1. codex plugin marketplace add SpaceZephyr/cowrite --ref main 2. codex plugin add cowrite@cowrite 3. codex plugin list, confirm Cowrite, 8 Skills, and Cowrite MCP are installed After installation, tell me that a new task is needed to load the plugin; in the new task, call cowrite_get_status and return the local canvas address. ``` You can also directly install in the terminal: ```bash codex plugin marketplace add SpaceZephyr/cowrite --ref main codex plugin add cowrite@cowrite ``` After installation, create a new Codex task and say: ```text Start Cowrite and tell me the local canvas address. ``` ### Let Claude Code Automatically Install Send the following command to Claude Code: ```text Please install Cowrite: https://github.com/SpaceZephyr/cowrite.git Please run in sequence: 1. claude plugin marketplace add SpaceZephyr/cowrite 2. claude plugin install cowrite@cowrite --scope user 3. claude plugin list, confirm Cowrite, 8 Skills, and Cowrite MCP are installed After installation, remind me to run /reload-plugins or open a new Claude Code session; after loading, call cowrite_get_status and return the local canvas address. ``` You can also manually execute in Claude Code: ```text /plugin marketplace add SpaceZephyr/cowrite /plugin install cowrite@cowrite /reload-plugins ``` Or directly use terminal commands: ```bash claude plugin marketplace add SpaceZephyr/cowrite claude plugin install cowrite@cowrite --scope user ``` ### What Happens During the First Startup When the plugin's MCP is loaded for the first time, it will automatically: 1. Check and install npm dependencies; 2. Build the Cowrite browser front-end; 3. Start the production service at `http://127.0.0.1:4320`; 4. Register the Cowrite MCP tool; 5. Persist pages and assets to `~/.cowrite/`. The first startup may take a few dozen seconds. The service only listens to the local machine and does not upload articles to remote. When the plugin session ends, the service started by the plugin will also stop; the next load will automatically resume. ## Running from Source ```bash git clone https://github.com/SpaceZephyr/cowrite.git cd cowrite npm install npm run dev ``` In development mode, it defaults to opening [http://127.0.0.1:4321](http://127.0.0.1:4321), and the API is located at `127.0.0.1:4320`. Test page data is saved in `data/cowrite.json`. If `4321` is occupied, Vite will display the automatically switched address in the terminal. ## Writing Workflow 1. When creating a new page, you can fill in the title and creation requirements, or import a `.md` / `.markdown` file from local; the import will automatically identify the first-level heading or use the file name. During editing, you can directly paste PNG, JPEG, GIF, or WebP images, and Cowrite will first store them in the local asset library and then insert a short link to avoid base64 causing page stutter. 2. Click the top "Cowrite", and choose between "Create according to the page content requirements" and "Input custom creation requirements"; the task will copy the current page text to the Agent dialogue box. 3. In the editor, select text, and use the floating toolbar's "Illustration", "HTML", "Optimization", or "Dialogue"; "Dialogue" will copy the draft with the original quote, paste it into the Agent input box, and then add modification requirements. 4. Click each Page's top "Slide", select PPT or HTML; PPT mode will generate editable PPTX and browser-openable PDF preview, and the Agent will insert the delivery link back to the top of the article. 5. Click "Typesetting", select WeChat public account or Xiaohongshu: WeChat public account generates replicable rich HTML; Xiaohongshu uses Codex's built-in `image_gen` to generate 3:4 image groups according to the confirmed strategy. 6. Click the top "Illustration", and after confirmation, the Agent will analyze the entire article, use Codex's built-in `image_gen` to generate 2-6 unified style 16:9 illustrations, and insert them into the corresponding paragraphs. 7. Click "Send", you can choose Feishu, WeChat public account, or Zhihu; Feishu confirms and creates a cloud document through the local `lark-cli`, and WeChat public account and Zhihu are temporarily marked as "to be completed". 8. The Agent reads the latest revision of the page, calls the specified Skill to produce the result, and then writes it back precisely through MCP. 9. The editor polls and updates, and people and Agent can continue to edit the same page; revision optimistic lock will prevent mutual overwrite. 10. When deleting a page, click the delete icon on the right side of the corresponding title in the left directory, and execute the deletion in the confirmation popup. ## Built-in Skill Routing | Cowrite Operation | Repository Skill | Fixed Product and Constraints | |---|---|---| | Illustration | `skills/image-studio` | Codex built-in `image_gen`, 16:9 images, prohibit external model fallback | | Whole Article Illustration | `skills/article-batch-illustration` + `skills/image-studio` | Automatically plan 2-6 anchor points, unified style, safe insertion | | HTML | `skills/text-logic-diagram` | 16:9 HTML/PPT style single page, inline CSS + SVG, suitable for iframe | | Optimization | `skills/ai-writing-assistant` | Method 5 partial rewriting, only replace selected text | | Slide | `skills/space-multi-design-ppt` | Intelligent brand matching; native editable PPTX + PDF browser preview, or 16:9 HTML deck | | Typesetting | `skills/space-wechat-layout` | Automatically match Claude / OpenAI / Google; WeChat public account replicable rich HTML preview page | | Xiaohongshu Typesetting | `skills/baoyu-xhs-images` + `skills/image-studio` | Two scheme confirmations; Codex built-in `image_gen` generates 3:4 image groups | | Page Read and Write | `skills/cowrite` | MCP operation, revision merge, anti-overwrite rules | The command copied by the button will explicitly declare the Skill name and confirmed parameters. All bitmap generation uniformly uses Codex's built-in `image_gen`, without configuring image API keys, and will not use external models or insert pictures of unknown origin. ## Built-in Image Generation Cowrite no longer includes LabNana, Gemini, or other external image API scripts. Illustration, whole article illustration, Xiaohongshu image, and Slide image modes all use Codex's built-in `image_gen`: - No need for `LABNANA_API_KEY` or `OPENAI_API_KEY` - Each different image is called once built-in tool - After generation, check first, then copy to the project directory, upload, and insert into Cowrite - Built-in tool unavailable or failed to stop, no CLI or external model fallback Codex provides built-in image generation, and the image button can be directly executed. Claude Code still can use page editing, typesetting, HTML, PPTX, and MCP capabilities; if the current runtime does not have Codex's built-in `image_gen`, the image task will explicitly stop and not automatically switch suppliers. ## Agent Access ```text .codex-plugin/plugin.json Codex plugin description and Skill entrance .agents/plugins/marketplace.json Codex marketplace .claude-plugin/plugin.json Claude Code plugin description .claude-plugin/marketplace.json Claude Code marketplace .mcp.json Codex / Claude Code dual-end MCP startup configuration scripts/start-plugin.mjs Automatic installation, construction, startup, and persistence skills/cowrite/SKILL.md Page read and write and concurrency rules skills/image-studio/ Codex built-in image_gen workflow, style, and prompt template skills/article-batch-illustration/ Whole article illustration planning, unified visual, and safe insertion rules skills/text-logic-diagram/ HTML/PPT logic diagram specification and template skills/ai-writing-assistant/ Article creation and partial optimization method skills/space-multi-design-ppt/ Article to PPTX / HTML Slides workflow skills/space-wechat-layout/ WeChat public account typesetting and replicable HTML preview template skills/baoyu-xhs-images/ Xiaohongshu content disassembly, strategy, style, and image group workflow ``` MCP provides seven tools: `cowrite_get_status`, `cowrite_list_pages`, `cowrite_get_page`, `cowrite_create_page`, `cowrite_update_page`, `cowrite_upload_asset`, and `cowrite_insert_after`. If you only want to temporarily load local source code without installing the marketplace, you can also use Claude Code's development parameters: ```bash claude --plugin-dir /absolute/path/to/cowrite ``` The plugin mode does not require manual maintenance of `npm run dev`; the self-starting runner will manage the production service. During source code development, still use `npm run dev`. ## Architecture ```text Browser Vditor ───────────────┐ ├─> Express API ─> ~/.cowrite/cowrite.json Codex / Claude + Skills ─MCP─┘ └─> ~/.cowrite/assets/ ``` - The service only listens to `127.0.0.1`, and the webpage itself does not execute Agent or Skill. - The marketplace installation mode uses `~/.cowrite/` for persistence; the source code development mode uses the repository's `data/`. - The list interface does not return the full text, and the Agent only reads the complete page when needed, reducing context consumption. - Pages with `prompt` and `revision = 1` will be displayed as "Waiting for Agent creation". - Images and HTML first enter the Cowrite asset library, and then are inserted into anchor points as Markdown images or iframes. ## Verification ```bash npm test npm run build npm run probe:plugin ```