Skip to content
WRITING AGENT

FAQ

Can I use a model other than DeepSeek?

Section titled “Can I use a model other than DeepSeek?”

Yes - there’s no lock-in. Pick any OpenAI-compatible host with /provider (or the first-run wizard), then point any node - or all of them - at any model that host serves, live and persisted:

/model critic openai/gpt-4o      # one node
/model deepseek/deepseek-v4-pro  # everything

The defaults (routing, temperatures, token budgets) are tuned for DeepSeek V4 Pro/Flash; other models work but aren’t tuned. See Model routing.

Do I need an API key to try it?

Section titled “Do I need an API key to try it?”

No. Fake mode (WRITINGAGENT_FAKE=1) runs the entire pipeline - state machine, TUI, exports - with deterministic placeholder output and zero token spend. You only need an OPENROUTER_API_KEY for real prose. See Quickstart.

Is my writing sent anywhere?

Section titled “Is my writing sent anywhere?”

No. It’s local-first - all manuscript data stays on disk. The only outbound calls are to your OpenRouter endpoint, the optional DuckDuckGo researcher (plus page fetches when deep_research is on), and optional Wikimedia image search. Telemetry is written only to .index/telemetry/ on your machine. Details in Privacy & security.

Can I hand-edit the output, or have the agent revise it?

Section titled “Can I hand-edit the output, or have the agent revise it?”

Both. The brain is plain markdown + JSON, so you can edit files directly. To have the agent do a guarded rewrite of one committed unit - with a diff to accept or reject - use revise --chapter N --instruction "...". See Review, revise & trust.

What happens if it crashes or I kill it mid-run?

Section titled “What happens if it crashes or I kill it mid-run?”

Nothing is lost. Every step persists atomically before the state advances, and resume guards prevent double-commits. Run run again and it picks up exactly where it stopped.

Do I need a GPU?

Section titled “Do I need a GPU?”

No. All generation happens via your configured model host’s API (OpenRouter by default, but any OpenAI-compatible host). The only optional local model is sentence-transformers (if you enable use_embeddings) - and it runs fine on CPU.

Is there a browser UI, or only the terminal?

Section titled “Is there a browser UI, or only the terminal?”

Both. writing-agent web opens a local browser dashboard (default port 8787) that runs the same pipeline as the TUI - Studio, a live run view over Server-Sent Events, per-project Evals / Artifacts / Rejected / Export / Cost, Telemetry, Skills, and Settings. It binds 127.0.0.1 only with no authentication, so it’s a single-operator tool - don’t expose it on a network. See Commands.

How long can a book be?

Section titled “How long can a book be?”

num_chapters defaults to 8 and is tunable (/set num_chapters N or --chapters N). The unit chain is sequential, so cost and wall-clock scale with length. Validated guidance on the practical ceiling is coming soon.

What does a run cost?

Section titled “What does a run cost?”

A 2-section article is ~$0.15. The biggest levers are max_revisions, divergent_drafts, deep_research, and use_images. Full breakdown and the max_run_tokens kill-switch are in Cost & performance.

Article or book - which mode?

Section titled “Article or book - which mode?”

Articles are thesis-driven long-form single pieces (sections, citations, a cohesion pass). Books are multi-chapter works where continuity matters (canon, consolidation, production). Switch with /mode article or /mode book.

Can I run it from a script / CI instead of the TUI?

Section titled “Can I run it from a script / CI instead of the TUI?”

Yes - every command works one-shot as writing-agent <command> ... (or python writingagent.py <command> ... from a source install), and fake mode makes it CI-safe. There’s also a stable Python API - an Agent + Project facade - for embedding the engine directly.

Why is it called WRITING AGENT but the command is writing-agent?

Section titled “Why is it called WRITING AGENT but the command is writing-agent?”

WRITING AGENT is the product name; the installed console script is writing-agent (pip normalizes the writing-agent package to that command). From a source clone you can also run it as python writingagent.py.