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.

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

Run inside Claude Code:

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

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.

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.

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.

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

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.

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.

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

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, rejected paths, the exact next action, and remaining verification available across sessions.

Owner walkthrough keeps your own objective verbatim and works it in coherent units for the hours you set. Choose it in Guided mode. It can finish early when the objective's acceptance criteria are verified; product evolution and coverage hunts continue until their deadline.

You can also plan with one model and execute with another: the on-disk contract and continuation records carry the work. Cross-host continuity explains the handoff and its limits.

To run later, Schedule prints the operating-system configuration and install command; it registers nothing itself. The command reference includes a terminal path that needs no live model session or remaining allowance.

• Choose permissions and checks. An unattended run cannot approve prompts. Verification can run per item, at the end, on a custom cadence, or never; the receipts state what actually ran. Configure optional guards through Owner knobs. They are hardening, not a sandbox.
• Stop always wins. Ask Nightshift to stop or use the offline stop command. Unfinished boxes stay open; the terminal path needs no live model session.
• Bound retries. A stalled finite shift remains held by default. Set a deadline or an explicit stall limit when you need a cost boundary. Open-ended work always requires a deadline.
• Check your host's recovery limits. The watchman requires positive failure evidence and inherits the recorded permissions by default. Recovery and stale IDE views have host-specific boundaries. The recovered headless worker can continue without you watching it.
• Review before publishing. Commits stay local unless the contract authorizes otherwise. Ticks are self-reported; item checks and human review determine whether the work is good.

The recovery signals, process lease, host differences, and limits are in How Nightshift works. The why and cost of the workflow explain the trade-offs behind the design.

Use the documentation index for the full reference, grouped by task.

• Vocabulary — the names of the working files and mechanisms.
• How Nightshift works — lifecycle, policy, recovery, and limits.
• Shift modes — choose and compose the work.
• Command reference — skills, scheduling, and offline controls.
• Owner knobs — permissions, verification, receipts, and retention.
• Receipts and token usage — live progress, per-item measurements, and host limits.
• Archive and continue — preserve finished shifts and carry open work forward.
• Troubleshooting — diagnose before repairing.

Catalog entries are a focused starting point: one Markdown contract and its checks. Human and AI-assisted contributions are welcome. Use the contribution map to choose an area; verification and the release process are in CONTRIBUTING.md.

If Nightshift is useful to you, star the repository to help other developers discover it.

MIT © Orwa Mahmoud