nightshift

Go to sleep with a backlog and wake up with merged PRs.

nightshift autonomously works through your GitHub issues while you are afk. Point it at a PRD (a Product Requirements Document, or spec, published as a GitHub issue), pick your favourite coding agent, and it handles the rest: branch, implement, PR, merge, repeat. It stops when every child issue is done. Inspired by the Ralph Wiggum loop pattern.

[!WARNING] nightshift selects work from native GitHub relationships, not issue-body text. Child issues must be sub-issues of the PRD (gh issue create --parent), declare dependencies with --blocked-by, and carry the ready-for-agent label. Bodies are not parsed for membership or ordering. The bundled skills produce exactly this shape.

Prerequisites

• Rust + Cargo: install via rustup
• Git
• GitHub CLI (gh) >= 2.94.0: install gh, then run gh auth login. nightshift uses this to read native issue relationships (parent, blockedBy) and find your repository.
• A coding agent: install and sign in to whichever agent you pass to --agent. You only need one. See Supported Agents.

Installation

cargo install nightshift-cli

The crate is published as nightshift-cli; the installed command is nightshift. This places the nightshift binary in ~/.cargo/bin, which is on your $PATH after a standard Rust install.

For the latest unreleased code:

cargo install --git https://github.com/Shaurya-Sethi/nightshift

Usage

nightshift --prd 12 --agent claude --model claude-opus-5
nightshift --prd 12 --agent claude --tui

Invocation profiles

An invocation profile is the agent, model, and reasoning effort used for one issue.

--agent is required and is the default for the whole run. Optional --model and --reasoning-effort apply to every issue unless a picker overrides them.

To choose per issue, add any of --pick-agents, --pick-efforts, --pick-models, or --pick-prompts (TTY only). --pick-efforts and --pick-models cannot be combined; the other pick flags stack with either. Enter keeps a default. q or Ctrl-C cancels the whole picker; a partial selection never starts a run.

Picker order, inheritance, dry-run, and agent-specific knobs: Invocation profiles.

Supported Agents

nightshift hands your agent a single prompt per issue. These agents work out of the box:

[!IMPORTANT] Cursor uses Model-Encoded Effort. Use --model or Cursor's model-only --pick-models preflight to choose a model slug that already represents the desired effort. nightshift never adds --reasoning-effort, rewrites Cursor model strings, or injects effort syntax into a model value. Cursor is invoked as agent, not cursor-agent.

When --model is omitted, nightshift lets the selected agent use its persisted default model. When it is provided, nightshift passes it through unchanged for agents with a documented non-interactive model flag. If an agent does not support that flag, nightshift fails fast and tells you to retry without --model.

nightshift validates at the capability level only: whether the selected agent supports model or effort selection, and, except for OpenCode's pass-through variants, whether an effort is in nightshift's documented agent-native set. It does not scrape model catalogs, validate model names, rewrite model slugs, or enforce model-specific effort matrices. The selected agent remains responsible for accepting a model and any model-specific effort subset.

To add support for a new agent, see CONTRIBUTING.md.

How It Works

nightshift works through your PRD one issue at a time, stopping when there is nothing left to pick up.

Each iteration starts from a clean state: nightshift checks out and pulls your base branch, then fetches all open ready-for-agent issues from GitHub. It keeps issues whose native parent is your PRD, then picks the lowest-numbered one whose blockedBy issues are all closed. If nothing is unblocked, it stops.

For the selected issue, nightshift constructs a unified prompt and pipes it to the coding agent via stdin. For details on prompt structures, default instructions, custom directives, and how nightshift manages isolated session context, see the Context Management & Session Lifecycle Guide.

Without --tui, the terminal shows only nightshift's own output (issue blocks, git hygiene, completion). --tui replaces that with a full-screen Watch Board. Agent stdout and stderr are discarded in both modes; use the agent's own UI or history for session detail. On failure, nightshift reports the process exit status, not agent log text. While the board is active, q / Ctrl-C stop after the current issue without killing the agent.

Details: Terminal output.

After the agent exits, nightshift checks that the issue is actually closed on GitHub. If it is, the loop continues from step one. If not, nightshift stops and tells you; the agent may have exited cleanly but left the issue open, which usually means something needs your attention.

Skills

nightshift ships three agent skills under skills/. They make it easy to publish a PRD, create child issues with the right parent and blocked-by links, and get a nightshift command that matches how you want to run.

Flow: plan with an agent (or otherwise) → to-nightshift-prd → to-nightshift-issues → recommend-nightshift-profiles (optional) → nightshift --dry-run → nightshift. The first two skills need an authenticated gh.

Installing

Recommended (requires Node for npx):

npx skills add Shaurya-Sethi/nightshift

No Node? Clone this repo and copy skills/ into your agent's skills directory.

Keeping Your System Awake

For long-running PRD loops, see docs/keep-alive.md.

Contributing

nightshift is under active development, and i'd love your help! Whether you are fixing a bug, adding support for a new coding agent, or proposing new features, all contributions are extremely welcome.

How to get involved:

• File an Issue: If you find a bug, encounter unexpected behavior, or have an idea for a new feature - Open an issue to start a discussion.
• Add a New Agent: Want to use nightshift with another coding assistant? Follow the step-by-step agent integration guide in CONTRIBUTING.md.
• Propose Other Changes: For parser, orchestrator, or CLI changes, please open an issue first so we can align on the design. Check out CONTRIBUTING.md for codebase style and testing guidelines.