Documentation
How Nightshift works
Understand the durable contract, one-item loop, gates, parked decisions, recovery, and morning handoff behind every Nightshift coding shift.
Updated
How does Nightshift keep a coding agent on the approved work?
Nightshift moves the working contract out of chat and onto disk. The agent reads one approved item, implements it, runs its gates, commits it locally, ticks it, and continues until the list is complete or the owner stops the shift.
The durable loop
Every item follows the same visible cycle. The punch list remains authoritative across compaction, restart, or a recovered session.
- Read the current item and gates.
- Build the complete outcome.
- Run the required verification.
- Create one local conventional commit.
- Write the item's receipt.
- Tick the item and continue.
Questions become decisions
An unattended run cannot wait for a sleeping owner. When a choice is genuinely yours, Nightshift selects a reversible default, records the reasoning and rollback in the parking lot, and keeps working. Known later work belongs on the drafting table instead.
- Parking lot: owner decisions and defaults chosen.
- Drafting table: known work staged for later.
- Snag log: findings and their disposition.
- Shift log: progress, recovery, and handoff events.
Recovery without a second worker
One shift binds one session identity and one process lease. A watchman starts a replacement only when host evidence shows the active process is gone and the recorded identity can be resumed or safely handed off.
- The punch list survives even when conversation history does not.
- The process lease prevents the older process from continuing observable tool work.
- Other normal tabs and conversations remain free to work.
Start asks nothing
Before it arms, Start runs one native preflight that prints a verdict per line: ok, warn, or refuse, with an explanation and the exact repair after any refusal. With work in the punch list it asks no question at all, which is what lets a scheduled 04:00 start and a watchman revival behave exactly like an interactive one. The only time it speaks is when the list is empty, and then it offers the staged drafts and parked orders.
- A shift is armed by a marker Start writes after the preflight passes, never by the list alone.
- Start refuses to place a second agent beside a live shift.
- The same verdict sentences print on POSIX and native Windows.
Start with a bounded prompt
This prompt names the outcome and preserves Nightshift’s review boundary. Paste it into the supported coding host from the project you want to change.
Explain how Nightshift would keep this project's objective, progress, decisions, and verification durable before I start a shift.What this workflow does not claim
- A checked box is self-reported; the gate does not independently prove implementation quality.
- Recovery preserves the work contract but cannot repair a host's conversation history or UI.
Evidence and sources
These links support the released behavior, public outcomes, or problem language described on this page.
Frequently asked questions
Is Nightshift just a long prompt?
No. The contract, decisions, progress, and recovery state live in project files, while hooks enforce the host boundaries the owner enabled.
Does the clock-out gate prove the work is correct?
No. It enforces completion of the declared list. Item definitions, project checks, and human review establish quality.
Does Nightshift need Python, Node, or jq?
No. Skills and hooks ship as shell and PowerShell. The rules file is read by a bundled reader on POSIX and by PowerShell on native Windows, and an unreadable file fails closed rather than arming on a guess.