overnight-runner

Overnight Runner

The overnight-runner CLI (installed at ~/.local/bin/overnight-runner from https://github.com/rizonetech/overnight-runner) keeps long autonomous runs honest. You do the work; the guard records evidence and refuses a final answer until the record supports it.

Always run it with the Claude state base:

export OVERNIGHT_RUNNER_BASE=.claude/overnight

If overnight-runner is not on PATH, do NOT improvise — tell the user and offer: curl -fsSL https://raw.githubusercontent.com/rizonetech/overnight-runner/main/scripts/install.sh | bash

Run protocol

1. Start: overnight-runner start <todo.md> — runs pre-flight (module detection, ChromeMCP health) and an adversarial todo review. Read the review output; add any guardrail items it proposes to the todo before working.
2. Work slice by slice. After each meaningful step record it: overnight-runner update --note "<what was done>" --gate <gate>=<status> ... Never check a todo item without evidence recorded in the same update.
3. Browser gates: browser_verification gates are satisfied through the chromemcp-browser skill (real MCP evidence). If the run genuinely has no UI work, the run may have been started with --no-browser — the waiver is recorded and must be echoed in the handoff, never hidden.
4. Blockers: when stuck, record it (overnight-runner update --blocker "<why>") and move to independent items instead of retrying in a loop.
5. Finish: overnight-runner finish-check must pass before you claim completion. If it fails, fix what it names or report honestly what is blocked. Then overnight-runner handoff and include its output in your final report.

Hard rules

• The guard's word beats your memory: if state says a gate is pending, it is pending.
• Never edit the state JSON by hand; only through the CLI.
• Never delete or reword existing todo items to make them pass; fix the work instead.
• overnight-runner status is cheap — run it whenever you resume or feel lost.