Caotang

Caotang

Caotang is a writing studio for novels and other long fiction. Your manuscript stays on your machine. An AI agent can work in it too. Plans and drafts wait for your approval, small changes apply at once, and each recent turn can be taken back within the checkpoint limits in Settings.

Caotang has the structure Scrivener writers know: a binder of chapters and scenes, a corkboard, an inspector, a codex of characters and places, and a compile step that writes Word, EPUB, Markdown or plain text. It also has editors for screenplay scenes (Fountain), branching dialogue (Ink) and storyboards with video prompt packs, and the compile step writes their formats too. The difference is the agent. Bring your own provider key and it works through the app's own commands. It proposes a plan, you approve or change it, and each turn that changes the project leaves a checkpoint you can restore, within the limits in Settings.

Try it at caotang.app, or open the app directly at caotang.app/app.

Caotang is free and MIT-licensed. There are no accounts, no subscriptions, no credit meters and no Caotang server. If you use a model provider, you pay that provider directly.

What works today

• Projects. Create, open, rename and remove projects in your browser. Set the title, author, language, ISBN and cover. Export a project as a .caotang bundle and import one back. In Chrome or Edge, open a project folder or save to one. A folder of a project this browser already keeps opens as that project when it holds the same book, and a folder of a project another tab has open is refused. Caotang asks before it saves over a change it did not make, or before it writes back a caotang.json that another program removed. A folder's writing sessions come into this browser when you open it.
• Binder. A manuscript of chapters and scenes, and a research section that is never compiled. Drag to reorder, rename, set a status or a label, delete and undo. A filter bar (text, status, label, word counts, keywords and recent dates) with saved filters, and a footer with word goals, a sprint timer, a writing history and the words a stopped tab kept.
• Corkboard. The scenes of a chapter, or the chapters of the manuscript, as cards in three sizes. Drag to reorder.
• Inspector. Synopsis, notes, keywords, status and label, codex links and scene declarations for the selected item, and the container settings of a dialogue.
• Editor. Scenes are Markdown and save as you type. Word counts, a daily target and focus mode. Agent drafts appear in the scene first, in a preview bar.
• Screenplays. A scene is Fountain, with a Script view, a Source view and a Pages view, which opens a line in the Source view. Import a .fountain or .fdx script as sections and scenes. Final Draft files have not yet been checked against Final Draft itself.
• Dialogue. A container is an Ink story, with an outline, a branch graph, findings and line ids. Import a .ink story as one container for each group of knots that divert to one another, or a Twee 3 story (.twee) as one container, after a report of the logic the import strips.
• Storyboards. Shot cards with pictures (chosen, dropped or pasted), an animatic total, script coverage, a prompt for each target video model, and a prompt pack that exports as JSON, Markdown or CSV.
• Codex. Characters, locations, objects, lore, subplots and other entries, with aliases, include policies, excluded phrases and a list of the documents each name appears in.
• Agent instructions and memory. Your standing instructions live in CAOTANG.md at the root of the project and ride every request, within a visible 1,500-token limit; the notes the agent keeps are plain files in a memory folder you can read, edit and forget. The agent writes either only behind a card you approve.
• Skills. Reusable writing instructions for the agent ("draft in close third person"), kept in the project as standard Agent Skills folders other tools read too. You read and approve each skill before the agent is told about it, and a change asks again. A skill guides the agent and changes nothing about what needs your approval.
• Macros. Save a plan you approved as a macro with a few values left to fill in, and run it again from Settings. The run shows the same card as any plan, one undo takes it back, and your rules and permission mode still apply. Only you run a macro; the agent cannot.
• Hooks. Write a check the agent is held to, such as a word it must not use, a status it must not touch, a length it must keep or a continuity check it must pass, and it runs before and after each of the agent's calls. A hook can warn, stop the step with its reason beside a greyed-out Approve, or leave the agent a note. It never approves anything, your rules and permission mode still decide, and only you can add or remove one (by hand in the project file until Settings has a panel for it). See Hooks.
• Findings. A quick scan of the manuscript against the codex and the scene declarations, and a model review that runs only after you approve its plan. Findings are grouped by severity and quote their passages. Dismiss one with a reason, mark it fixed, or send it to the agent with Fix with agent. The run history keeps each run.
• Agent. Plans, one-step cards and draft previews in the agent panel (or, if you choose it in Settings, the agent's new text kept in the scene with only the changed words marked for you to accept or reject), with checkpoints and restore, and a Trace tab that shows what each turn sent and got back (kept only in the open tab, exported on request). Stop a running turn, steer it with a note, or queue your next message while it works. A Mode control sets who answers its cards: Plan only, Ask (the default), Accept edits or Auto, with limits that stop a turn on a question. A plan that needs five or more model calls can run in the background while you write, and you review what it drafted before anything is applied. For a long reading job it can hand the reading to a helper agent, which only reads and suggests; a suggestion happens only if it is in the plan you approve. It runs on presets for the major providers (Anthropic, OpenAI, Google, xAI, Mistral, DeepSeek, OpenRouter and more) or any OpenAI-compatible endpoint you add, or on the built-in demo provider with no key. It uses native tool calling where the model supports it, and can run the model review as a plan step, and call the tools of the MCP servers you connect and enable (see below).
• Export. Markdown, plain text, Word (.docx) and EPUB, for the whole manuscript or one folder of it (a part or a chapter). For screenplays, dialogue and storyboards: Fountain, Final Draft (.fdx, not yet checked in Final Draft itself), a paginated screenplay PDF, an Ink story, a dialogue table, a shot list and a storyboard contact sheet (PDF, also as blank numbered frames to draw in, with photographs of the drawings dropped back on their shots). Also a coherence report. Recipes keep your export settings.
• Settings. Provider profiles, the agent's context budgets, the daily target and autosave delay, coherence checks, light and dark themes, checkpoint limits, MCP & tools, and data.
• MCP & tools. Settings can connect external Model Context Protocol servers over Streamable HTTP. Each server's tool list is reviewed before its tools are used, and a tool can be switched off. The agent calls an enabled tool at once only when its server is trusted for reads and the tool is read-only. Any other call waits for your approval.
• Caotang as an MCP server. Other AI tools can read a project folder, attach its documents, notes, codex and story timeline as resources, and run prompts that carry the context Caotang gathers for a scene. With writes allowed, they can change it, and each change that asks is confirmed in the host. See Caotang as an MCP server.

Not in this build yet: the desktop wrapper. docs/USER-GUIDE.md lists it with the rest, and docs/ROADMAP.md has the order.

Requirements

• Node.js. The engines field of package.json allows Node 22.19 or later in the 22 line, 24.x, and 26 or later. Continuous integration tests the 22.19.0 floor and Node 24; Node 26 is allowed but not covered.
• pnpm 12.9.1, pinned in packageManager. On Node 22, update Corepack first with npm install --global corepack@0.34.3; Node 22.12's bundled Corepack 0.29.4 could not verify pnpm's current signing key. Then run corepack enable.
• A browser. The app is written for current browsers. End-to-end tests gate every pull request in Chromium, Firefox and WebKit; the Firefox and WebKit suite also runs nightly and on demand. Opening and saving a project folder needs Chrome or Edge, or another Chromium-based browser. Bundles work in any browser.
• A window at least 960 px wide for the desktop layout. Under 1100 px the toolbar wraps onto a second row and the side panels narrow. Under 960 px (a phone or a tablet held upright) Caotang uses a narrow layout: the binder is a drawer, the inspector a sheet, and the corkboard, storyboards, dialogue branch graphs, the screenplay Pages view, MCP & tools and compile formats other than Markdown and plain text say "Open on desktop". It is tested in an emulated Chromium, not on real phones, and there is no sync, so export a backup.

Install and run

From the repository root, after you clone it:

pnpm install

pnpm dev

pnpm dev serves the app at http://127.0.0.1:5173.

For a production build, run pnpm build, then pnpm --filter @caotang/desktop preview. The build goes to apps/desktop/dist/, with a THIRD-PARTY-NOTICES.md beside it. The preview serves it at http://127.0.0.1:4173 by default. Two things to know about it:

• The build works at the root of its origin, so serve it from the root, as the preview does, unless you built it for a sub-path with CAOTANG_BASE (see Self-hosting).
• Projects are kept per origin, which is the address and the port together. A project you made at http://127.0.0.1:5173 does not appear at http://127.0.0.1:4173. Export a bundle to move one.

Self-hosting

Caotang is static files, so any static host can serve it: GitHub Pages, Netlify, Cloudflare Pages, an S3 bucket, or nginx on your own machine. There is no server part to run.

1. Build it: pnpm install, then pnpm build. The site is everything in apps/desktop/dist/, with THIRD-PARTY-NOTICES.md beside it. Copy the whole folder.
2. Serve it over HTTPS. Browsers offer the WebCrypto key sealing and the folder access Caotang uses on secure origins only (https://, or http://localhost and http://127.0.0.1 on your own machine).
3. Serve it at the root of its origin (https://writing.example.com/), or build it for a sub-path with CAOTANG_BASE: CAOTANG_BASE=/caotang/ pnpm build makes a build that works at https://example.com/caotang/. By default the build's asset paths start at /.
4. Folder saves need a Chromium browser (Chrome, Edge, Brave, Arc and the like), which have the File System Access API. In other browsers, projects live in the browser and move as .caotang bundles.

Projects are kept per origin: a project made on one host does not appear on another. Export a bundle to move one.

The build's index.html already carries its Content-Security-Policy in a tag. A host that can send headers can send the same policy as a header, and add the protections a tag cannot (frame-ancestors):

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; f