nightshift

nightshift

Give the agent a shift. Come back to work you can review.

Nightshift gives Claude Code, OpenAI Codex, and Cursor a durable work contract for long coding runs. Bring a task list, choose a ready-made shift, or give your agent an objective and hours to work. A clock-out gate holds unfinished work, progress survives on disk, and a watchman can recover failed sessions. Review the results, per-item token usage and time where available, then archive the shift with its evidence intact.

MIT licensed · macOS, Linux, Windows · No separate service or API key

Install · First shift · Real runs · Why it exists · Documentation · Website

What you want	What Nightshift provides
Finish the work you already planned	A persistent punch list, item-by-item verification, and a gate that rejects premature clock-out.
Put a few hours into the project	Open-ended product evolution, coverage hunts, or your own objective, with an explicit deadline and a continuation record.
Start without writing a backlog	Ready-made shifts through Hunt and Quality. Choose the work yourself or let the agent compose it; review first or run directly.
Keep a long run moving	Progress across compaction, parked decisions, deduplicated findings, and recovery under the host's supported signals.
See what the work consumed	Runtime-measured token usage and duration per item, with host-specific gaps clearly marked.
Review today and continue tomorrow	Live receipts, a morning receipt, and archived history that keeps unfinished work available for the next shift.

Choose a shift · Receipts and token usage · Archive and continue

The four-hour first night left nine focused items as reviewable commits. A later 45-hour contract survived a host handoff and became a human-reviewed 67-commit pull request. These are documented runs, not benchmarks.

Why Nightshift

It started with eight requested changes and a screen saying the four hard ones deserved a “focused session.” The agent had finished the easy work and left the rest for later.

Nightshift makes the remaining work explicit at every attempted stop. The list survives context compaction, decisions go into a parking lot with a default, and a watchman can recover failed sessions. The checks and your review still determine whether a completed item is good. Read the story and see the original screenshot →

Install

Codex and ChatGPT

Install Nightshift from the official OpenAI Plugin Directory.

For local Codex development, install the same package from its marketplace:

codex plugin marketplace add orwa-mahmoud/nightshift
codex plugin add nightshift@nightshift

Open the project you want Nightshift to change in Codex, or connect Codex to its GitHub repository. A Git repository or a persistent local folder works. A disposable ChatGPT scratch conversation cannot preserve project changes, so Setup redirects you to Codex before writing run state.

Claude Code

Run inside Claude Code:

/plugin marketplace add orwa-mahmoud/nightshift
/plugin install nightshift

Cursor

Open Customize → Add → From GitHub Repository, paste https://github.com/orwa-mahmoud/nightshift, choose a scope, and select Import. Then select Nightshift from the imported marketplace to install it. The Cursor Directory listing is for discovery; installation happens inside Cursor. Read the host-specific recovery and CLI limitations before starting a shift.

Platforms

macOS and Linux use the bundled Bash runtime. Native Windows uses bundled PowerShell, with no Git Bash or WSL required. For WSL, keep the host, plugin, repository, and watchman in one Linux distribution. See Native Windows and Remote environments for platform details.

Your first shift

Start with one small task in a project you trust. Keep the first run attended and use the first-night safety checklist before leaving a longer run alone.

Action	Codex: ask Nightshift	Claude Code
Set up	“Set up Nightshift in this project.”	/nightshift:setup
Start	“Start the Nightshift shift.”	/nightshift:start
Check progress	“Show Nightshift status.”	/nightshift:status
Diagnose	“Diagnose this Nightshift workspace.”	/nightshift:doctor
Stop	“Stop the Nightshift shift.”	/nightshift:stop

1. Set up. Review the proposed checks and permissions. Setup asks before applying them.

2. Write one item under ## Items in .nightshift/punch-list.md. For a repository that already has a test runner, a small first task could be:

   - [ ] **1. Document how to run the tests.**
     - Find the test command configured in this repository.
     - Add it to the README with its prerequisites and the directory to run it from.
     - Verify: run the documented command and check that the instructions match it.
     - Commit: `docs: explain how to run the tests`
   

   Use an outcome that matters to your project. The title names the result, the bullets bound the work, Verify states how to check it, and Commit names the local change. More filled examples are in the example punch list.

3. Start. With work queued, Start checks the workspace and permissions, then arms the shift and works the list without another question. If it refuses, it names the repair. An empty list offers staged work instead of silently starting something new.

4. Review. Inspect the change, the checks that ran, and each item's receipt. Push only when you decide to. If progress looks wrong, Doctor reports the workspace state without changing it; follow Troubleshooting.

The punch list holds the work. Gates are the project checks, run on the verification cadence you choose. The parking lot records decisions and defaults; the shift log records progress and problems, and the vocabulary names every working file. A tick is the agent's completion claim, not independent proof of quality.

A persistent folder without Git works too: artifact mode completes an item through artifact receipts under .nightshift/receipts/. Source and checkpoint receipts stay local. See Evidence and receipts for what to review.

The morning

Start with the morning receipt: how the shift ended, what verification ran, what was unavailable or disabled, and what needs your attention. Then read in this order:

• The receipts index — .nightshift/receipts/README.md lists every item with its state, its tokens, and its time, so the shape of the night is one table.
• Any item's receipt — .nightshift/receipts/NN-slug.md holds that item's story: what was delivered, what was tried and rejected, how it was verified, and where the output landed. It updates during the work, so you can read a long-running item before it finishes.
• The diff or output files — the work you will accept, revise, or reject.
• The parking lot and the snag log — defaults to accept or reverse, and the findings whose disposition is something other than fixed.

Token usage and time, per item

The runtime appends a Tokens table and a Time table to each item's receipt at its tick, and repeats the figures in the index. Input, output, cache, and reasoning retain the host's counting rules; missing readings stay explicit. Choose progress updates by time, tokens, either, or completion only. These control what is written, not a spending limit. Receipts and token usage explains the measurements and limits; the example receipts show them in context.

Archive the shift, keep the next step

Ask Nightshift to archive the finished work (/nightshift:archive in Claude Code). Completed items and handled records move into dated history; open work, unanswered decisions, and the punch-list contract stay live. Filed receipts keep working links to their evidence, and a history index makes prior shifts easier to revisit. Enable automatic filing at clock-out if you want that part handled too. Pruning old history is a separate, explicit retention choice. Archive and continue explains what is filed and what the next shift inherits.

The real runs library follows real shifts through their review, including a 45-hour contract that survived a host handoff and became a human-reviewed 67-commit pull request. It also includes a template for reporting a bad night without hiding what happened.

Two kinds of shift

• A finite list. Write the items yourself or approve work staged on the drafting table, then Start works that list. It ends at the last tick; an optional deadline caps the run.
• A goal with a clock. Hunt composes work from the ready-made catalog. Product evolution and coverage hunts continue until quitting time; a defect hunt can finish earlier when a complete pass finds no new defects. Each entry declares its ending.

Ask Hunt to select the work automatically, or choose catalog entries yourself. Independently, choose to review the plan first or start immediately. For example, after Setup:

Use Nightshift for four hours to improve this product's onboarding. Inspect the project, propose the work, and wait for my approval before starting.

Quality uses the same choices for tests, lint, dependencies, documentation, accessibility, and other applicable quality debt. Named GitHub issues can be staged with Import issues, then promoted into the punch list. Import issues searches nothing and writes nothing back to GitHub. The four combinations and ready-to-use requests are in Shift modes.

Ready-made work, with a contract

The ready-shift catalog covers work such as defect repair, dependency upgrades, release readiness, developer onboarding, documentation, accessibility, SEO audits, and research synthesis. Each entry carries its own discovery method, definition of done, verification, and ending. Hunt can combine compatible entries under one budget; the Maintainer night preset follows onboarding, documentation drift, CI warnings, and release readiness in order.

Product evolution studies the project and its users, records evidence, ranks opportunities, and builds complete improvements until quitting time. Its opportunity map keeps completed work,