Overnight supervisor for
headless coding agents
Queue small, verifiable tasks before going to bed. Wake up to one isolated git branch per task and a verified test report.
Unattended Execution Safety
Why NightShift makes unattended work safe
Fresh Process per Task
AI agents running in single long sessions suffer severe context rot and exponentially growing token costs. NightShift spawns a completely fresh sub-process for every task.
External Test Gate
The agent self-reporting "I finished the task!" counts for nothing. NightShift runs your real test gate (npm test, cargo test). If tests fail, the code is rejected.
Ephemeral Git Worktrees
Every task is given an isolated worktree under .nightshift/work/<id>. One bad task cannot poison the next, and nothing is ever merged into main automatically.
Execution Pipeline
How a task travels through NightShift
tasks/queue/01-auth.md is atomically moved to tasks/queue/.running/ so multiple runners or crashes cannot process duplicate tasks.
.nightshift/work/01-auth on branch nightshift/01-auth pinned to the base commit.
.nightshift/prompt.md. Agent runs non-interactively. Output streams directly to .nightshift/logs/01-auth.jsonl.
gate: ["npm test"].
Commits branch nightshift/01-auth, moves to tasks/done/, and appends diffstat to .nightshift/REPORT.md.
Reverts changes, moves task to tasks/failed/, logs failure reason, and captures agent blocker report.
Quick Start Guide
From zero to overnight running in 5 minutes
Run inside your project's root git repository to generate the configuration and task queue folders.
nightshift init
Diagnoses Node.js version, Git repository status, and confirms your AI agent CLI is available in PATH.
nightshift doctor
Open nightshift.config.json and define the check commands that the agent's work must pass.
{
"harness": "claude",
"gate": ["npm test", "npm run build"],
"protect": ["tests/**", "*.test.*", ".github/**", "package-lock.json"]
}
Scaffold the file from the terminal, then fill in the outcome and the acceptance criteria:
# Let NightShift write the shell of the file nightshift add "fix the expired session redirect" --minutes 20 # Then edit tasks/queue/fix-the-expired-session-redirect.md --- minutes: 20 turns: 30 gate: npm test -- tests/auth --- # Fix Expired Session Redirect When the auth token expires, redirect `/dashboard` to `/login?expired=true`. Do not modify any test definitions or add dependencies.
Run a simulated pass for free, then launch the real unattended run:
# 1. Test plumbing with fake agent (zero API cost) nightshift run --dry-run --once # 2. Run the overnight queue for real nightshift run
Supported Agents
Works with your favorite coding assistant
Native stream-json output parsing with exact dollar budget tracking.
Executes with full auto json flags directly in the isolated worktree.
Runs OpenCode non-interactively with auto-approved permissions.
Interactive Generator
Generate a Task File
Fill in your task details to generate a formatted markdown file ready to place into tasks/queue/.
tasks/queue/ before running NightShift.
Pull Request Mode
Wake up to reviewable PRs, not loose branches
By default a finished task stays on a local branch. Add one flag and the morning inbox is full of pull requests instead.
nightshift run --create-pr
// nightshift.config.json
{
"pullRequests": {
"enabled": true,
"base": "main",
"draft": true
}
}
The verified work is committed on nightshift/<task-id> inside its own worktree.
The branch is pushed to origin and its upstream is set, so it is ready to review.
A pull request is opened through the GitHub CLI with the task, diffstat, gate result, and cost in the body.
NightShift never merges. If the GitHub CLI is missing or not logged in, the run still succeeds and prints the compare URL so you can open the pull request yourself. The branch on disk is never lost.
Cloud Overnight Runner
Let GitHub run the night instead of your laptop
Laptops sleep when the lid closes. A scheduled runner does not.
name: nightshift
on:
workflow_dispatch:
schedule:
- cron: "0 2 * * *" # 02:00 UTC
permissions:
contents: write
pull-requests: write
jobs:
run:
runs-on: ubuntu-latest
timeout-minutes: 360
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Install nightshift
run: npm install -g @junaedkhandakar/nightshift
- name: Install agent CLI
run: npm install -g @anthropic-ai/claude-code
- name: Run nightshift
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: nightshift run --create-pr
- name: Summarise the night
if: always()
run: cat .nightshift/REPORT.md >> "$GITHUB_STEP_SUMMARY"
The full template ships with the package at templates/github-action.yml. Every step that needs your input is marked.
Under Settings -> Secrets and variables -> Actions, add ANTHROPIC_API_KEY or OPENAI_API_KEY.
Push task files into tasks/queue/ during the day. The runner picks them up at 02:00 UTC and hands back pull requests.
The report is written to the job summary and uploaded as an artifact, so you can read the night in the morning without checking out anything.
CLI Handbook
Command & Flag Reference
| Command | Purpose | Example |
|---|---|---|
| nightshift init | Scaffolds nightshift.config.json and queue directories |
nightshift init |
| nightshift add | Writes a task file into the queue, ready to edit | nightshift add "fix login redirect" |
| nightshift list | Tables of queued, failed, and finished tasks with reasons | nightshift list |
| nightshift doctor | Diagnoses Node, Git, config, and agent CLI readiness | nightshift doctor |
| nightshift run | Executes all tasks in tasks/queue/ sequentially |
nightshift run |
| nightshift run --once | Processes only the next single task then exits | nightshift run --once |
| nightshift run --dry-run | Runs the pipeline using dummy agent (zero API spend) | nightshift run --dry-run --once |
| nightshift run --create-pr | Pushes each finished branch and opens a pull request | nightshift run --create-pr |
| nightshift status | Prints queue counts, spend, and tail of REPORT.md |
nightshift status |
| nightshift retry <id> | Moves failed task back into the active queue | nightshift retry 001-fix-auth |
| nightshift pr <branch> | Opens a pull request for a branch that already has a commit | nightshift pr nightshift/001-fix-auth |
| nightshift clean [--all] | Prunes finished worktrees (optionally removes branches) | nightshift clean --all |
| nightshift -v, --version | Prints installed CLI version | nightshift -v |
FAQ & Troubleshooting
Frequently Asked Questions
What happens if the agent fails or enters an infinite loop? ↓
NightShift enforces strict process-tree wall-clock timeouts via limits.minutes (default 45 mins). If a task exceeds its allotted minutes or conversational turns, NightShift terminates the process tree, records the timeout in REPORT.md, moves the task to tasks/failed/, and safely moves to the next task.
Does NightShift push directly or merge into my main branch? ↓
Never. NightShift never pushes to remote or merges into main automatically. Every successful task produces its own isolated git branch (nightshift/<task-id>). You inspect the branch and diff in the morning and merge only what you trust.
What are protected paths? ↓
By default, tests/**, *.test.*, .github/**, and package-lock.json are protected. If a lazy agent attempts to pass a test gate by deleting test assertions or commenting out tests, NightShift detects the modification, rejects the task immediately, and quarantines it.
Where should I run NightShift overnight? ↓
Since laptops sleep when the lid is closed, run NightShift on an always-on home server, a secondary mini-PC, a cloud VPS inside tmux (tmux new -s night), or via GitHub Actions (see templates/github-action.yml).