Nightcrew

Why it exists

I built Nightcrew because I wanted an agent that could build from my backlogs overnight without me having to trust its word that the work is done. Coding agents are happy to open a pull request and declare success, and I found that checking those claims by hand costs almost as much as writing the code myself. Nightcrew inverts that: the pull request that lands in front of me in the morning carries its own proof, a table that maps every acceptance criterion to concrete evidence in the diff, backed by an independent re-run of the tests.

It is deliberately opinionated. This is how I run it; fork it and make it yours.

Quick start

# clone and install
git clone https://github.com/SeanL128/nightcrew && cd nightcrew && uv sync
# enroll a repo (runs its tests live, refuses repos where they fail)
uv run nightcrew enroll /path/to/your/repo
# one full pass: pick → plan → build → gate → PR
uv run nightcrew run

Requires Python 3.11+, uv, git, an authenticated gh CLI, and at least one dispatch backend (the claude or codex CLI, or an OPENROUTER_API_KEY).

Configuration

Two files. Each enrolled repo carries a nightcrew.yaml holding its test command and spec items, and one fleet.json describes the repos, the dispatch roles, and the spending caps.

• config.test_cmd The repo's test command, run live at enrollment and re-run independently by the gate on every build. required
• items[] Spec items with an id, a description, acceptance criteria, and dependencies. Items with fewer than two real criteria are skipped as underspecified, not guessed at. required
• dispatch.roles Per-role backend: a command template (claude -p, codex exec, any CLI) or an OpenRouter model. The gate refuses to run when the judge and builder resolve to the same model family. fleet.json
• caps Daily and per-run dollar caps plus a max item count, enforced at the item boundary; a tripped cap stops the run and logs it. fleet.json

Usage

• nightcrew run One full pass over the fleet: backfill PR outcomes, then per repo pick the first ready item, build it in an isolated worktree, gate it, allow one fix attempt, and open a PR only on a passing gate.
• nightcrew enroll <repo> Validates the repo's spec, runs its tests live, and refuses enrollment if they fail, because a repo without working tests cannot be gated.
• nightcrew status Per-repo outcome tallies, total recorded cost, and the last run's summary from the build log.
• nightcrew digest The last N runs' item records, gate results and PR links, plus the PRs still awaiting review.

The full command, flag, and file reference lives in docs/USAGE.md.

How it works

A run is a chain of small, inspectable stages rather than one prompted black box. The picker takes the first ready item from the spec, skipping anything underspecified, blocked by dependencies, or already covered by an open PR. The planner turns the item into a self-contained brief. The builder dispatches that brief to a configured backend inside a dedicated git worktree on branch nightcrew/<item>, with off-limits paths enforced on the staged diff.

Then the gate, which is the whole point. First the deterministic half: the tests are re-run independently in the worktree, because the builder's claim that they pass is not evidence, and a tamper check blocks any diff that removes or weakens tests. Only then does the evidence judge run, a model from a different family than the builder, which must map each acceptance criterion to concrete evidence in the diff and test output. Any unaddressed criterion blocks the PR. A blocked build gets exactly one fix dispatch and one re-gate before Nightcrew gives up and logs why.

A passing gate commits the worktree, pushes the branch, and opens a pull request whose body is the criterion-to-evidence table with the run's cost. Merging is always left to a human. On disk a run touches only a SQLite build log (nightcrew.db by default), temporary nightcrew-wt-* worktrees that are removed when each item completes, and the fleet file during enrollment; there is no installer, so uninstalling means deleting the clone and the log.

Status & roadmap

Nightcrew runs nightly on my own repos and has shipped real gated PRs; the public packaging is the current work.

• Full pipeline: pick → plan → build → gate → fix → PRDone
• Hybrid gate: independent test re-run, tamper check, cross-family evidence judgeDone
• Fleet CLI: enroll / run / status / digest with a SQLite build log and dollar capsDone
• Portable scheduling recipes: GitHub Actions, cron, systemdDone
• First public release (v0.1.0)In progress
• Value learning and a trust ratchet, gated on real outcome dataPlanned