nightshift

The crew that builds while you're gone.

Nightshift runs walk-away, CI-dispatched, multi-workstream engineering programs: a human plans interactively, launches, and leaves. The run always terminates — in either a draft PR with a run report and a decision ledger, or a partial build with a diagnosis, a rollback point, and a one-command retry. Nothing blocks silently; nothing waits mid-run for a human who is not there.

Trust comes from reversibility and legibility, not prevention: every decision an agent makes is journaled with its alternatives, tagged to the commit before it applied, and revocable by replay. You come back to a shift handover note — what got built, what was decided along the way and why, and how to flip anything you disagree with.

Install

Published as @wildorder/nightshift; the executable is named nightshift. Always spell the full scoped name when using npx outside a project that has it installed — npx nightshift looks up the unscoped name on the registry, which is not this package (and an unrelated night-shift package exists, so a typo installs someone else's code):

npx --yes @wildorder/nightshift --help

Getting started

What you need before anything else:

• Node.js 20+ and a git repository (an existing project or a fresh one).
• At least one coding-agent CLI installed and authenticated on the machine that will run programs — claude (Claude Code) and codex are the two exercised daily. Two different providers is the intended shape: the reviewer and decider should not share a provider with the implementer (see "No self-grading" below), and one seat surviving the other's quota exhaustion is a real resilience property, not a bonus.

1. Set up the package and the planning skill:

npx --yes @wildorder/nightshift setup

This adds the devDependency and installs the /plan-program and /init-project skills into the agent tools detected on your machine (nightshift doctor shows what was found and where).

2. Scaffold the project structure:

npx nightshift init

Creates AGENTS.md (agent directives with a shared universal block), CLAUDE.md, docs/vision.md, docs/programs/, tasks/, and a nightshift.config.json with your verify commands detected from package.json. Existing files are never overwritten. Then write two things only you can write:

• docs/vision.md — what this product is and where it is going. Every authoring and review agent reads it; a placeholder vision produces placeholder specs.
• The agent roles in nightshift.config.json — init scaffolds the verify commands but not the agents, because only you know what is installed and paid for on your machine. This repository's own configuration is a working example:

{
  "agent":         { "command": "claude", "args": ["-p", "--model", "sonnet", "--permission-mode", "acceptEdits", "--allowedTools", "Bash(npm run build:*)", "Bash(npm run typecheck:*)", "Bash(npm run lint:*)", "Bash(npm test:*)"], "promptMode": "stdin" },
  "authorAgent":   { "command": "claude", "args": ["-p", "--model", "opus", "--permission-mode", "acceptEdits"], "promptMode": "stdin" },
  "deciderAgent":  { "command": "codex", "args": ["exec", "--model", "gpt-5.6-sol"], "promptMode": "stdin" },
  "reviewerAgent": { "command": "codex", "args": ["exec"] },
  "recoveryAgent": { "command": "codex", "args": ["exec", "--model", "gpt-5.6-sol"], "promptMode": "stdin" }
}

Only agent is required to run; every other role degrades loudly, not silently, when absent. The verify commands are the contract every workstream must pass — the runner checks them on the untouched tree before the first agent spawns and refuses to start if they are red, so the first failure you debug is the environment's, named as such, not eight workstreams' worth of budget spent on it.

The implementer's --allowedTools grant mirrors the verify commands on purpose: a headless Claude invocation with only --permission-mode acceptEdits can edit files but cannot run Bash, which leaves the agent fixing test failures it can never re-run. Granting exactly the verify commands lets it run the same gate it is graded against — the runner's own independent verification remains the only thing that gates a commit. The runner warns at startup when it detects a Claude implementer without such a grant.

3. Plan a program — in your agent tool (e.g. Claude Code), run:

/plan-program

Planning is the interactive half of the bargain: you design, scope, and decompose with the model, and it writes the manifest, the program document, and the program branch. Keep a first program small — two or three workstreams — while you learn what the crew does with your specs.

4. Run it:

npx nightshift run <program-id>

Run the first one locally and watch. You come back to a run report at docs/programs/<program-id>-run-report.md, a decision ledger beside it, and one commit per verified workstream on the program branch.

5. (Optional) Move runs to CI:

npx nightshift ci init github

Writes a manual-dispatch workflow (--runner self-hosted for a box with your subscription-authenticated agent CLIs; the default hosted variant wires API-key agents instead). The self-hosted variant needs a GH_TOKEN repository secret with repo scope — a background runner cannot unlock the keychain gh auth login uses, so the workflow hands git and gh the secret explicitly. Dispatch is always manual — a run is a deliberate act:

gh workflow run nightshift.yml -f program-id=<program-id>

Status

Alpha. The full lifecycle operates end-to-end and this repository is built by it — planning, spec authoring, implementation with verify-gated commits, spec and test critique, decision triage, red-path failure diagnosis, publish to a draft PR, and the end-of-run as-built snapshot refresh. Seven programs have shipped through it to date, including the machinery doing the shipping. The founding charter is docs/learnings.md — what its predecessor, @wildorder/program-pipeline, taught us; the settled principles live in AGENTS.md. Young enough that you should read the run report, every run.

The shape of a run

  /plan-program        HUMAN   design, scope, decompose (interactive)
    nightshift run ┬ author            one clean agent per workstream, by dependency level
                   ├ review            critic→writer rounds (2–3), fail-open into the ledger
                   ├ build             implement, verify, commit; decisions journaled
                   └ report            run report + decision ledger on the draft PR

Five agent roles, five jobs (nightshift.config.json):

| Block | Job | | --- | --- | | agent | Implements workstreams. A cheaper model is usually right. | | authorAgent | Writes each workstream's spec before it is built. Writing a spec is design reasoning, not implementation — a cheap agent model tends to write sparse, context-free specs, so this defaults to something more capable. Falls back to agent, loudly, when absent. | | deciderAgent | Makes, ratifies, or escalates decisions — and composes the human ping when one is warranted. Expensive model, different provider than agent. | | reviewerAgent | Independent second opinion: spec critique, test critique, whole-program review. Never the implementer. | | recoveryAgent | Retries failed workstreams; a distinct provider also survives primary quota/session failures. |

Core rules, inherited from hard experience:

• Decide-and-continue. Agents surface decisions as fenced blocks; the runner journals them, tags the pre-decision commit, and proceeds on the best default. Two-way doors are ratified post-hoc by the decider; one-way doors are decided before they apply. Escalation pings the human but never blocks a reversible path.
• Bounded loops fail open into the ledger, never closed into a gate.
• No self-grading. Reviewer and decider are different providers than the implementer; the runner runs verification itself and owns commits.
• Failure isolation. A failed workstream parks; everything outside its downstream cone still builds. Partial + diagnosis is a valid outcome.
• Every artifact is written for a human first. Specs are narrative documents; machine data lives in the manifest.

Authoring specs

nightshift run authors every missing workstream spec before it builds anything, but you can run just that stage on its own — after editing a plan, or to see the specs before a build starts:

nightshift author <program-id>

A taskFile that already exists is always kept, never overwritten. To deliberately re-author one after a plan edit, name it explicitly and force it:

nightshift author <program-id> --only WS-03 --force

--force on its own does nothing to existing specs — it only takes effect for ids named in --only, so a bare --force can never silently regenerate a program's worth of hand-reviewed specs.

Flipping a decision

Every decision an agent makes lands in the run report with a ledger id. When you disagree, rule on it directly instead of doing git surgery by hand:

nightshift decide <program-id> <decision-id> --choose <label> --reason "..."

This always records your ruling as the decision's binding entry — even a confirmation is authority worth journaling. If your choice differs from what got built, it prints what a replay would roll back and reset; add --replay to actually do it:

nightshift decide <program-id> <decision-id> --choose <label> --reason "..." --replay

Replay rolls the repository back to the decision's anchor commit, resets exactly the workstreams whose built state that removes, and leaves the rest complete. It preserves the pre-replay state under a refs/nightshift/ ref and never loses a ledger event. It ends by telling you the one command to re-run — the rebuilt work honors your ruling, since the next run's implementer brief carries it as binding.

Development

Requires Node.js 20+.

npm ci
npm run build
npm run typecheck
npm test
npm run lint

License

MIT © 2026 Wing It Labs