gustavo-ferreira03/specbook

*A self-hosted QA agent that turns plain-language behavior into Playwright tests you can read.*
Features • Get started • How it works • CLI • CI • Private networks • Configuration • Development
Describe a flow in chat, and Specbook explores your app in a real browser, writes a **Spec** (a readable contract plus a Playwright test), runs it and keeps the evidence. When a Spec fails, the agent investigates in a browser you can watch and proposes a repair that keeps the intended behavior.
Features
- **Specs people can read**: every check is a spec.yml with preconditions, steps and one expected result, paired with an executable spec.ts that keeps a screenshot of that result on every run.
- **An agent that does the legwork**: it maps your app, proposes Specs, signs in with stored credentials and asks only when it is blocked.
- **Evidence for every run**: screenshots per step, video on failure, diagnostics and run history live next to the Spec.
- **QA for your coding agent**: Claude Code or Codex create and verify Specs against your local app through the specbook CLI.
- **Checks on every deploy**: publish verified Specs to your team and run them on schedules and in CI.
- **Yours to host**: one container, your model provider, credentials encrypted at rest and projects stored in Git.
Get started
With Docker installed, run:
Open localhost:4001. The setup wizard creates the admin account, connects a model provider and adds your first project; the bundled Sauce Demo project is a quick way to try it.
The container holds everything: the web app, the agent, both browsers and the test runner. Data lives in the specbook volume, so updating is a docker pull and a new docker run with the same volume.
> [!TIP]
> To serve Specbook on a domain, point your reverse proxy at port 4001 and add -e FRONTEND_ORIGIN=https://specbook.example.com. Extra hostnames go in -e SPECBOOK_ALLOWED_HOSTS=host1,host2.
OpenAI device-code login and Anthropic's copy-the-code login work out of the box. The browser login that redirects back to localhost also needs -p 127.0.0.1:1455:1455 (OpenAI) or -p 127.0.0.1:53692:53692 (Anthropic).
How it works
1. Create a project with your app's URL and describe a behavior in chat.
2. Pick the Specs the agent proposes. When it needs to sign in, it asks through a secure form, never in the chat.
3. Open a Spec to run it and inspect the evidence. On a failure, the agent investigates and proposes a repair.
4. Keep it running from **Project settings → Automation**, with schedules and CI access.
A Spec pairs a readable contract with its test. Each precondition, step and the expected result becomes a named step(), so every run keeps a screenshot of the result. An optional cleanup() removes data the Spec creates:
spec.yml spec.ts
Specbook validates every test against a restricted Playwright subset before it runs.
Use the CLI with your coding agent
The specbook CLI works on your machine, including against localhost, with no Specbook server. Its brain is the coding agent you already use (Claude Code or Codex), so there is no model to configure. Install the latest release (or /api/cli/specbook.tgz to match your team's server):
Creating Specs is a conversation: Specbook asks when it is blocked, proposes Specs to select, and asks for logins through specbook credentials add, never in the chat. init installs a skill so your agent knows the workflow. Specs live in .specbook/ in the same format the server uses.