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

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

Recommended: the full plugin for local Codex. Install it from the repository marketplace:

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

Add the marketplace once per Codex installation. Review and trust the plugin's hooks (/hooks in the CLI), then start a new conversation. The full plugin carries the clock-out gate, safety rules, session recovery, and per-item token usage and time.

Skills-only edition. The official OpenAI Plugin Directory listing works the punch list, receipts, parked decisions and continuation notes with the session's own tools. Directory versions up to 0.25.3 carry the full plugin; later versions are skills-only, because the directory does not accept lifecycle hooks. It has no clock-out gate, recovery or usage accounting, so it suits attended sessions and ChatGPT. Its Setup offers the full plugin; after installing it, turn the directory copy off so one Nightshift is enabled.

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.

skills.sh

npx skills add https://github.com/orwa-mahmoud/nightshift --skill install-nightshift

This adds one small skill, kept in this repository's root skills/ folder, that installs the full plugin into Claude Code, Codex or Cursor. Nightshift's own skills need its hooks and runtime, so they are marked internal and install only as part of the plugin.

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.

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>-<id>.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 architecture diagram — .nightshift/receipts/architecture.md, kept current item by item.
• The diff or output files — the work you will accept, revise, or reject.
• The parking lot and the snag log — .nightshift/inbox/: 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,