nightshift

nightshift is a set of patterns and tools designed to facilitate the safe and efficient use of coding agents like Claude Code for overnight tasks, ensuring that users wake up to productive results rather than unintended consequences.

Continuously running a coding agent overnight can lead to significant discoveries, but the reality often includes unexpected crashes or endless error loops, resulting in wasted resources and unreliable output. nightshift addresses these challenges by providing essential standards and small bash utilities that enhance the reliability of unattended runs without the need for complex frameworks or dependencies.

Key Features

The project is structured around four fundamental patterns that enhance the execution of overnight tasks:

1. Resumable Handoff File

To manage interruptions effectively, a single file maintains the state of the run, including the current goal, status, next actions, and known issues. This ensures that, in case of interruptions, the run can resume seamlessly without sacrificing the progress made. For implementation details, refer to templates/HANDOFF.md.

2. Verification Gates

Prevent trusting an agent’s output blindly by implementing verification gates. These checks ensure that only validated output passes through, using build processes, tests, or other validations to confirm integrity before moving forward. More about this can be found in bin/verify-gate.

3. Runaway Awareness

Set hard limits to prevent runaway processes that can lead to extensive resource consumption. This can be achieved by implementing maximum iterations, wall-clock deadlines, and emergency stop files. The tools for this are available in bin/runaway-guard.

4. Morning Brief, Not a Scrollback

To facilitate easier review, the run outputs a concise summary highlighting decisions, accomplishments, costs, and notes. This format ensures that users can quickly grasp what was done and what requires their attention, aided by tools like bin/nightlog and bin/morning-brief.

Quickstart

nightshift is entirely composed of bash scripts without external dependencies. Users can quickly explore the functionality by cloning the repository and running a demonstration script:

git clone https://github.com/toolshedlabs-hash/nightshift
cd nightshift
./examples/demo.sh

This demo simulates a typical overnight run, showcasing the built-in safeguards and summarization tools available.

For typical usage, integrate the scripts into your existing process setup while maintaining easy access to the bin/ directory:

while runaway-guard --max-iters 40 --max-minutes 480; do
  # Perform a unit of work with your coding agent
  nightlog done "refactored the parser and added a test"
  if ! verify-gate "npm test" "npm run build"; then
    nightlog blocked "tests failed after the parser change, needs a look"
    break
  fi
done

# Generate a morning brief
morning-brief > MORNING-BRIEF.md

To manually stop a running process, simply create a stop file:

touch .nightshift/STOP

Tools Overview

Why Choose nightshift

By focusing on discipline rather than complexity, nightshift empowers users to implement successful nightly coding runs. The minimalistic approach ensures that each tool is transparent, easily customisable, and directly applicable to various setups.

Additional Information

A Pro Pack version is available for those seeking enhanced features, including cost monitoring and more sophisticated orchestration capabilities. More details can be found on the nightshift website.

Contributions and feedback are encouraged to improve the toolkit further, ensuring better overnight runs for all users.