Installation

Requirements

Python 3.10+ with pip - the engine (CI covers 3.10-3.13)
Linux, macOS, or Windows - all code paths are portable
A model-host API key for real runs - any OpenAI-compatible host (OpenRouter, OpenAI, Anthropic, DeepSeek, …); offline fake mode needs none

Install (pip - recommended)

pip install writing-agent      # gives you the `writing-agent` command
# ...or isolated, so its deps stay out of your global env:
pipx install writing-agent

Then, from anywhere:

writing-agent                                  # launch the interactive TUI
writing-agent web                              # or drive it from a local browser dashboard
writing-agent write --abstract "an article on vector databases"
writing-agent new --abstract "..."             # create a project
writing-agent run                              # drive it to completion
writing-agent export --format pdf

Install (from source)

Hacking on the engine? Clone and install editable:

git clone https://github.com/vikast908/WritingAgent
cd WritingAgent
pip install -e .          # core
pip install -e ".[dev]"   # + pytest + ruff, if you hack on it

This gives you the writing-agent command directly (or run it as python -m writingagent).

Optional extras

Everything below degrades gracefully when absent - install only what you use.

Extra	What it adds	Install
Deep research fetcher	`scrapo-ai` fetches clean page markdown and escalates HTTP → browser → stealth for hard pages, plus its Playwright browser tier (Python 3.11+)	`pip install "writing-agent[deep]"` then `python -m playwright install chromium`
Firecrawl search/scrape	Firecrawl search API + page scraping (`search_provider: firecrawl`) - more reliable under volume	set `FIRECRAWL_API_KEY` in `.env` (no extra install)
DOCX export	pandoc converts the manuscript	`winget install pandoc` / `brew install pandoc` / `apt install pandoc`
PDF arrowhead fidelity	cairosvg rasterizes SVG diagrams (otherwise they render as vector art via svglib, with arrowheads simplified)	`pip install cairosvg` (needs system cairo on Linux)
D2 diagram layout	the D2 CLI lays out diagrams with ELK - an explicit opt-in via `/set diagram_engine d2` (`auto`, the default, uses the zero-dependency built-in renderer and does not auto-select D2 even when the binary is present)	install the `d2` binary (release/script) or point `WRITINGAGENT_D2` at it, then `/set diagram_engine d2`
Semantic skill retrieval	sentence-transformers embeddings (`use_embeddings: true`)	`pip install sentence-transformers`

Configuration files

These live in the agent home - $WRITINGAGENT_HOME if set, otherwise the OS user-data dir (%LOCALAPPDATA%\writingagent on Windows, ~/Library/Application Support/writingagent on macOS, $XDG_DATA_HOME/writingagent on Linux) - never the repo or install tree, so a pip install never writes config near site-packages.

File	Purpose
`.env`	your model-host key (e.g. `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …; required for real runs), optional `WRITINGAGENT_PROVIDER` (pin the host), optional `*_BASE_URL` (override a host’s OpenAI-compatible base URL), optional `FIRECRAWL_API_KEY` (enables `search_provider: firecrawl`)
`config/settings.yaml`	All behavior toggles - see Settings
`config/models.yaml`	Per-node model routing (copied out of the bundled defaults on first run) - see Model routing

Where your writing lives

Everything is plain markdown + JSON on disk under brain/, inside the agent home above:

<agent home>/brain/users/<you>/
  books/<project>/        chapters, plan, canon, manuscript.md, exports
  articles/<project>/     sections, thesis, sources, manuscript.md, exports
  skills/                 learned craft skills (markdown, promoted by efficacy)
  voice/                  admired passages that the writer matches