Skip to content
WRITING AGENT

Quickstart

1. Install

Section titled “1. Install”
Terminal window
pip install writing-agent      # Python 3.10+ · gives you the `writing-agent` command
# or, isolated:  pipx install writing-agent

Prefer to work from a clone? See the installation guide for the from-source and optional-extras paths.

2. Add your API key

Section titled “2. Add your API key”

Writing Agent is model-agnostic: it runs on any OpenAI-compatible host and has no blessed default. Pick one (OpenAI, Anthropic, DeepSeek, Google, Groq, Perplexity, OpenRouter, a local Ollama / LM Studio, …) and set that host’s key in a .env in your working directory. The first-run wizard also prompts you to choose. OpenRouter is the widest-reach starting point (one key fronts every vendor and reports real USD cost):

Terminal window
OPENROUTER_API_KEY=sk-or-...          # or OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, ...
# WRITINGAGENT_PROVIDER=openai         # optional: pin the host (else use the wizard / `/provider`)

3. Write something

Section titled “3. Write something”

The fastest path is the one-shot write command. It asks every clarifying question upfront (audience, depth, length, tone, must-includes, byline, output format), then runs fully autonomously to a finished, exported file (new projects default to article mode):

Terminal window
writing-agent write --abstract "The psychology of decision fatigue"

Answer the short interview, then watch the live dashboard: each section is drafted, critiqued, revised if needed, humanized, and committed. At the end you get a summary card - words, time, cost, insight scores - and an exported file.

You can also launch the interactive TUI with no arguments and drive it from there:

Terminal window
writing-agent
❧ write --abstract "The psychology of decision fatigue"

Prefer a browser?

Section titled “Prefer a browser?”

Run the same pipeline from a local web dashboard instead of the terminal:

Terminal window
writing-agent web            # opens http://127.0.0.1:8787 in your browser

It runs the identical engine - start a run from Studio, watch it stream live, and browse each project’s evals, artifacts, cost, and export options. The server binds 127.0.0.1 only with no authentication, so it’s a single-operator tool; pass --port N to change the port or --no-browser to skip auto-opening.

Prefer step-by-step control?

Section titled “Prefer step-by-step control?”
new --abstract "The psychology of decision fatigue"   # plan + outline (you approve it)
run --manual                                          # write it, pausing to review
export --format pdf                                   # ship it

Runs are autonomous by default; pass --manual (or /auto off) to be shown the outline for approval, pick among divergent first drafts, and get a one-keypress escalation menu on any stalled section.

Try it offline first (no API key)

Section titled “Try it offline first (no API key)”

Fake mode runs the entire pipeline with canned model outputs - state machine, TUI, exports, everything except real prose:

Terminal window
# PowerShell
$env:WRITINGAGENT_FAKE=1; writing-agent
Terminal window
# bash
WRITINGAGENT_FAKE=1 writing-agent

Next steps

Section titled “Next steps”