FAQ

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?

No. Fake mode (WRITINGAGENT_FAKE=1) runs the entire pipeline - state machine, TUI, exports - with deterministic placeholder output and zero token spend. For real prose you need a key for whichever host you configure (e.g. OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, …; local hosts like Ollama need none). See Quickstart.

Is my writing sent anywhere?

No. It’s local-first - all manuscript data stays on disk. The only outbound calls are to your configured model host, 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?

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?

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?

No. All generation happens via your configured model host’s API (any OpenAI-compatible host - there’s no blessed default). 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?

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?

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?

A minimal 2-section article lands around ~$0.15 (~15 calls, ~84k tokens); a full agentic article (6 sections, divergent drafts, diagrams, claim-checks) runs to about ~$0.52 at the other end. 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?

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?

Yes - every command works one-shot as writing-agent <command> ... (or python -m writingagent <command> ...), 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?

WRITING AGENT is the product name; the installed console script is writing-agent (pip normalizes the writing-agent package to that command). You can also run it as python -m writingagent.