NS
NightShift
Version 0.2.0 Released: task tooling, pull request mode, and a cloud runner

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.

$ npm install -g @junaedkhandakar/nightshift
Node.js >= 20 • Git >= 2.30 • Claude • Codex • OpenCode

Unattended Execution Safety

Why NightShift makes unattended work safe

01

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.

No 8-hour context decay • Strict turn caps
02

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.

Exit 0 required • Protected path guards
03

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.

Clean reviewable branches • Zero main tree pollution

Execution Pipeline

How a task travels through NightShift

1
Atomic Queue Lock
tasks/queue/01-auth.md is atomically moved to tasks/queue/.running/ so multiple runners or crashes cannot process duplicate tasks.
2
Clean Worktree Provisioning
Cuts a fresh git worktree at .nightshift/work/01-auth on branch nightshift/01-auth pinned to the base commit.
3
Agent Invocation via Pointer
Instructions write to .nightshift/prompt.md. Agent runs non-interactively. Output streams directly to .nightshift/logs/01-auth.jsonl.
4
Protected Path Audit & Test Gate
NightShift checks if the agent touched test definitions or CI locks. If clean, it runs gate: ["npm test"].
Pass: Commit & Report

Commits branch nightshift/01-auth, moves to tasks/done/, and appends diffstat to .nightshift/REPORT.md.

Fail: Quarantine & BLOCKED.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

Step 1 Scaffold your repo

Run inside your project's root git repository to generate the configuration and task queue folders.

nightshift init
Step 2 Verify environment with doctor

Diagnoses Node.js version, Git repository status, and confirms your AI agent CLI is available in PATH.

nightshift doctor
Step 3 Set up your Test Gate

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"]
}
Step 4 Write a Task in tasks/queue/

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.
Step 5 Test Free (Dry Run) & Start Overnight

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

Claude Code Default

Native stream-json output parsing with exact dollar budget tracking.

--harness claude
Needs: claude CLI logged in or ANTHROPIC_API_KEY
OpenAI Codex Supported

Executes with full auto json flags directly in the isolated worktree.

--harness codex
Needs: codex CLI logged in
OpenCode Supported

Runs OpenCode non-interactively with auto-approved permissions.

--harness opencode
Needs: opencode CLI installed

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/add-health-check.md

          
Place this in 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.

Enable it
nightshift run --create-pr
Or set it permanently
// nightshift.config.json
{
  "pullRequests": {
    "enabled": true,
    "base": "main",
    "draft": true
  }
}
01. Commit

The verified work is committed on nightshift/<task-id> inside its own worktree.

02. Push

The branch is pushed to origin and its upstream is set, so it is ready to review.

03. Open

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.

.github/workflows/nightshift.yml
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"
1. Copy the template

The full template ships with the package at templates/github-action.yml. Every step that needs your input is marked.

2. Add your agent key

Under Settings -> Secrets and variables -> Actions, add ANTHROPIC_API_KEY or OPENAI_API_KEY.

3. Commit your tasks

Push task files into tasks/queue/ during the day. The runner picks them up at 02:00 UTC and hands back pull requests.

4. Read the summary

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).