A real Claude Code session. The agent can only read and edit files, so it can't run anything itself. When it tries to stop, doneguard starts a throwaway Postgres, seeds it, runs the unit tests and the Playwright tests, and sends back both failures.
Codex runs a project's hooks once you approve them (`/hooks` in Codex), and Copilot once you trust the folder. The recordings do that for the one run ([codex.tape](https://github.com/abranchesia/doneguard/blob/main/demo/codex.tape), [copilot.tape](https://github.com/abranchesia/doneguard/blob/main/demo/copilot.tape)).
```bash
cd your-project
doneguard init # detects the stack and your agents, writes .doneguard.conf, adds the hooks
doneguard check src/app.ts # optional: dry-run the checks on any file
```
Then restart your agent so it loads the hooks, and:
1. **Read `.doneguard.conf`.** One line per check, plain text. Delete what you don't want, add what's missing ([format](#configuration)).
2. **Commit `.doneguard.conf`.** Your team and your CI share the same checks.
3. **Work as usual.** Old errors elsewhere in the repo don't matter: doneguard only looks at files changed in the session.
Using an agent that `init` didn't find (or several)? Name them: `doneguard init codex gemini`, or `doneguard init all`.
Already have a `.doneguard.conf`? `init` never rewrites it, but it lists what it detects now and the file doesn't have yet. `doneguard init --update` adds those lines, each where it works: `cheats` on top, a database right above the tests that need it. Your lines and comments stay as they are.
## Start a new project from zero
In an empty folder there's nothing to detect yet. Run `init` once to install the hooks, scaffold the project, then run `init` again: it fills in the checks as soon as it finds a stack.
```bash
mkdir my-app && cd my-app
doneguard init # hooks installed, 0 checks for now
npm init -y && npm i -D typescript vitest && npx tsc --init
doneguard init # now detects tsc + vitest
```
Letting the agent scaffold the project? Tell it: *"once the project is set up, run `doneguard init`"*. The config is read on every stop, so the checks kick in right away.
## Tests that need a database
Integration tests usually need a database with the schema and some data in it. When `init` sees that your project talks to one, it adds a line for it right above the tests, at the end of the file:
```text
*.ts,*.tsx | @package.json | filter | npx --no -- tsc --noEmit --pretty false -p .
* | . | postgres=postgres:17-alpine | npm run db:migrate && npm run db:seed
*.js,*.jsx,*.ts,*.tsx | @package.json | files | npx --no -- vitest related --run --passWithNoTests
```
Right before the first check below it runs, doneguard:
1. **starts a throwaway database** in Docker, on a free port of `127.0.0.1`. Same image as your `docker-compose.yml` when there is one (pgvector and PostGIS included), so the version and extensions match.
2. **points your project at it.** For every check below, doneguard overrides `DATABASE_URL`, every variable holding a URL of the same kind in your `.env` files or your shell (`DIRECT_URL`, `POSTGRES_PRISMA_URL`…), and every URL variable your ORM config reads (Prisma's `env("…")`, `process.env.…` in `drizzle.config` and `knexfile`). For Postgres it also sets `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD` and `PGDATABASE`. dotenv, Prisma, Next.js, Vite and pydantic all let a real environment variable win over `.env`.
3. **migrates and seeds it** with the command on the line, with `NODE_ENV=test`. A broken migration or seed is reported to the agent as the cause, and the tests after it are not run, so it isn't buried under fifty "relation does not exist" errors. If the command can't run at all, the tests below are skipped rather than run on an empty database.
4. **runs the checks below it**, then **removes the container**. If the run is killed, the container still removes itself after 15 minutes.
If no check below it runs (only a README changed, or no related tests), no database starts. With the image cached, Postgres is ready in about a second.
| Detected by | Database | Environment |
|---|---|---|
| `pg`, `postgres`, `psycopg`, `asyncpg`, gem `pg`, Prisma `provider = "postgresql"`, or a `postgres`/`postgis`/`pgvector` image in compose | `postgres` | `DATABASE_URL`, `PG*` |
| `mysql2`, `mysqlclient`, `pymysql`, Prisma `provider = "mysql"` | `mysql` | `DATABASE_URL` |
| `redis`, `ioredis`, `bullmq` | `redis` | `REDIS_URL` |
| `mongodb`, `mongoose`, `pymongo`, `motor`, `mongoid` | `mongo` | `MONGODB_URI`, `MONGO_URL` |
The migrate and seed command `init` writes:
| Project | Command |
|---|---|
| Prisma | `prisma migrate deploy` (or `prisma db push` without migrations), then your `db:seed`/`seed` script or `prisma db seed` |
| Drizzle | `drizzle-kit push`, then your seed script |
| Knex | `knex migrate:latest`, then your seed script |
| Other Node projects | your `db:migrate`/`migrate` and `db:seed`/`seed` scripts |
| Alembic (when `env.py` reads the environment) | `alembic upgrade head` |
| Rails | `RAILS_ENV=test bin/rails db:prepare` |
| Django, Redis, MongoDB | `-` (nothing: Django's test runner builds its own test database) |
`init` only writes a migrate and seed command when it can see the connection comes from a variable it redirects: the ORM config reads a URL variable, or, for plain npm scripts, your `.env` files hold a database URL. Otherwise it writes `-` and tells you to fill it in. A config that builds the connection from `DB_HOST`, `DB_USER`… can't be redirected that way, so doneguard never runs a migration through it on its own.
**Docker not running?** The database and the checks below it are skipped, never failed, and doneguard says so (Claude Code shows it after the turn). `init` puts these lines last, so your linters and the stacks that don't need a database still run. Your tests don't need a database after all? Delete the line.
## End-to-end tests with evidence
With `@playwright/test` and a `playwright.config.*` that starts the app (`webServer`), `init` adds an `e2e` line. When the agent changes a page, a component or a stylesheet, doneguard runs the suite in a real browser and keeps everything in your project:
```text
.doneguard/
├── .gitignore # "*": evidence stays out of git unless you delete this
└── evidence/
└── 2026-10-30_12-08-37/
├── report/ # npx playwright show-report .doneguard/evidence/2026-10-30_12-08-37/report
└── results/
└── cart-two-mugs-cost-20-00/
├── test-failed-1.png # what the page looked like when it failed
├── error-context.md # the page as text, for the agent
├── video.webm
└── trace.zip # npx playwright show-trace …
```
- **Every test gets a screenshot and a video**, passing or not; failures also get a trace. Your own Playwright config is used as is: doneguard wraps it for the run (a temporary `.doneguard.playwright.config.*` next to yours) only to add the evidence and the output folder.
- **When a test fails, the agent gets** the error, the paths of the failure screenshot and the page snapshot, and opens them like any other file. Claude Code reads screenshots.
- **Which server the tests hit:** without a test database, `CI` is unset, like a run in your terminal, so a `webServer` with `reuseExistingServer: !process.env.CI` reuses the dev server you already have running. With a test database, `CI` stays set, so Playwright starts its own server pointed at it; if your dev server holds the port, the check is skipped and doneguard tells you, instead of clicking through your dev database.
- **The last 10 runs are kept.** Older ones are deleted.
- **No browsers installed?** The check is skipped until you run `npx playwright install chromium`.
- **Timeout:** 7 minutes, then the check is skipped.
`test-failed-1.png` from the run above: two mugs in the cart, total $10.00. The agent sees this.
Any other runner works too: put `{evidence}` in the command and doneguard replaces it with that run's folder. pytest-playwright gets one automatically when there is a `tests/e2e` or `e2e` folder. Cypress needs your app running, so `init` suggests a line instead of writing it:
```text
*.py,*.html,*.css,*.js | . | e2e | pytest -q --tb=short tests/e2e --screenshot on --video on --tracing retain-on-failure --output {evidence}
*.tsx,*.css | . | e2e | npx --no -- start-server-and-test dev http://localhost:3000 'cypress run --config screenshotsFolder={evidence}/screenshots,videosFolder={evidence}/videos,video=true'
```
## No shortcuts
An agent that can't get a test to pass will sometimes make the check pass instead, and one that needs an API key will sometimes paste it straight into the code. `init` adds a `cheats` line that sends back what was **added in the session**:
| Group | Catches |
|---|---|
| `skips` | `test.skip`, `.only`, `xit`, `@pytest.mark.skip`/`xfail`, `t.Skip()`, `#[ignore]`, `@Disabled`, `markTestSkipped`… in test files |
| `silencers` | `@ts-ignore`, `@ts-expect-error`, `eslint-disable`, `biome-ignore`, `# type: ignore`, `# noqa`, `//nolint`, `#[allow(…)]`, `@SuppressWarnings`, `rubocop:disable`… |
| `any` | `as any`, `: any` in TypeScript |
| `secrets` | AWS, Anthropic, OpenAI, Stripe, GitHub, Slack and Google keys, and private keys, in files git would commit (your gitignored `.env` isn't checked). Shown cut short, never whole |
| `deleted-tests` | test files deleted in the session |
```text
[.] cheats: changes that hide failures or leak secrets
src/cart.test.ts:7 test.skip skips or focuses a test: that hides the failure instead of fixing it
```
- **Only what the agent added.** doneguard compares against a git snapshot taken when the session starts (`git stash create`, which touches nothing), so the skips and ignores already in your code don't count.
- **Each one is flagged once.** If the agent keeps it, it has to say why in its final answer, and doneguard lets it stop and tells you (Claude Code shows it).
- **`doneguard check`** lists them without failing: they're aimed at agents, not at the `eslint-disable` you wrote on purpose.
- Some of them are fine in your project? Drop the group from the line: `* | . | cheats | skips,deleted-tests`.
## Without hooks: CI, git hooks, any agent
`doneguard check` runs the same checks on your git changes (or on the files you pass, or with `--base ` on everything the branch changed), one progress line per check, and exits 1 on failure. No agent needed. The GIF in [End-to-end tests](#end-to-end-tests-with-evidence) shows it.
**GitHub Actions**, on everything the pull request changed, with the result in the run's summary:
```yaml
on: pull_request
jobs:
doneguard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- run: npm ci # install your project's tools
- run: npx playwright install --with-deps chromium # if you have e2e tests
- run: pipx install doneguard
- run: doneguard report --base origin/${{ github.base_ref }} >> $GITHUB_STEP_SUMMARY
```
GitHub's Ubuntu runners have Docker, so the test databases work there too.
**Git pre-commit hook:**
```bash
printf '#!/bin/sh\nexec doneguard check $(git diff --cached --name-only)\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```
**Agents without a stop hook** (Cline, Windsurf Cascade…): add to `AGENTS.md` or the agent's rules: *"Before saying you're done, run `doneguard check` and fix everything it reports."*
## Stats
doneguard keeps a tiny local log of every checked stop. Ask it how many times it caught your agent:
```text
$ doneguard stats
doneguard stats since 2026-10-30
stops checked 2 in 1 session(s)
"done" blocked 1
fixed by the agent 1 of 1 (100%)
most failing vitest (1)
agents claude (2)
Caught 1 broken "done" claim(s); the agents fixed 100% on their own.
```
That's the real output of the session in the GIF at the top: one stop blocked by Playwright and vitest, fixed on the next try. The log lives in `~/.local/state/doneguard/log.jsonl` (or `$XDG_STATE_HOME`) and stores only times, agent names, results and tool names: no code, no paths. Delete it to start over.
## Show it
**Every turn, in Claude Code.** When everything passes, doneguard says what it checked, so you see it working and not only when it blocks:
**In a pull request.** `doneguard report` runs the same checks and writes the result as markdown:
```bash
doneguard report --base origin/main | gh pr comment --body-file - # a PR comment
doneguard report --base origin/${{ github.base_ref }} >> $GITHUB_STEP_SUMMARY # the summary of a GitHub Actions run
```
```markdown
### ✅ Checked by doneguard
| Check | Result | Time |
|---|---|---|
| cheats | ✓ passed | 0.0 s |
| tsc | ✓ passed | 0.6 s |
| postgres | ✓ passed | 0.9 s |
| postgres setup | ✓ passed | 0.3 s |
| vitest | ✓ passed | 0.7 s |
| playwright | ✓ passed | 1.0 s |
```
When something fails, the report says what, and exits 1.
**In your README.** [](https://github.com/abranchesia/doneguard)
```markdown
[](https://github.com/abranchesia/doneguard)
```
## Day to day
- **You don't run anything.** The hooks fire on their own when a session starts and every time the agent tries to stop. In Claude Code, a line under the agent's answer says what passed: `doneguard: ✓ cheats · tsc · vitest (3.1 s)`.
- **When a check fails**, the agent gets the errors and keeps going. You see it fixing things instead of saying "done".
- **If it still fails after 3 tries**, the agent stops (Claude Code shows `doneguard: checks still failing after 3 fix attempts`).
- **After an e2e run**, the screenshots and videos are in `.doneguard/evidence/`, newest last. Open the report with `npx playwright show-report .doneguard/evidence/