nightshift — Claude Code and Codex plugin: timed agent shifts
nightshift hands the agent a time-boxed shift with a punch list kept on disk, per-item receipts, and a run history you can review in the morning.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install nightshift@awesome-codex-pluginsWhat nightshift does
Nightshift turns a long unattended run into a shift with an end time. You supply a punch list in .nightshift/punch-list.md under ## Items, pick a ready-made Hunt or Quality shift, or set a goal plus hours, and the agent works through the items until clock-out. Progress and the decisions taken stay on disk, so the shift survives compaction and a resumed session. Hooks keep unfinished work from slipping out at the end, and a watchman brings back sessions that died.
Each item gets a receipt that updates as the work moves: status, tokens and duration pulled from host records, with anything the host cannot measure marked as such. Once the review is done, archive the shift with a date and its evidence; open items and unanswered questions stay live for the next run.
Open a Git repository or a persistent folder first — throwaway scratch workspaces won't do. Bash covers macOS and Linux, PowerShell covers native Windows, and there is no extra service or API key. Ticks are self-reported, so the item checks and your own review are what decide whether the output holds up.
What it helps with
- run an overnight shift against a punch list
- see token usage and wall time per item
- recover a crashed session and pick up where it stopped
- archive a finished shift with its evidence
- park open questions for the morning review
Example prompts for the agent
- Set up Nightshift in this project with
/nightshift:setupand show me the checks it proposes. - Start the shift with
/nightshift:startand work through.nightshift/punch-list.mduntil clock-out. - Archive the finished shift with its date and keep the open items live.
How to install nightshift
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install nightshift@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about nightshift
How do I install nightshift in Claude Code?
Add the marketplace first: /plugin marketplace add hashgraph-online/awesome-codex-plugins, then install the plugin: /plugin install nightshift@awesome-codex-plugins.
What does nightshift do?
It runs a long agent session as a shift with an end time: a punch list on disk, per-item receipts with tokens and duration, session recovery, and an archive of finished runs.
What do I need before the first shift?
A Git repository or a persistent folder; scratch workspaces are not supported. Then run /nightshift:setup, add one small item under ## Items in .nightshift/punch-list.md, and keep the first run attended.
Source text
nightshift · MIT
# Nightshift **Give the agent a shift. Come back to work you can review.** Nightshift gives Claude Code, 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. Hooks hold unfinished work at clock-out, a watchman can recover failed sessions, and progress and decisions stay on disk. Review the results, per-item token usage and time where available, then archive the shift with its evidence intact. - **Choose the work:** Hunt and Quality offer ready-made shifts, Guided or Automatic selection, and review-first or immediate execution. - **Work for hours:** product evolution, coverage hunts, and owner-defined walkthroughs preserve the current work and exact next action across sessions. Each has an explicit ending. - **See progress and usage:** each item receipt updates during work; the runtime adds per-item tokens and duration from host records, marking unavailable measurements explicitly. - **Keep useful history:** archive finished shifts with linked receipts and evidence, while open items and unanswered decisions remain live. Automatic filing is optional. MIT licensed. Bash on macOS and Linux, PowerShell on native Windows. No separate service or API key. Ticks remain self-reported; the item checks and your review determine whether the work is good. ## Install Codex — recommended, the full plugin from the repository marketplace: ```text codex plugin marketplace add orwa-mahmoud/nightshift codex plugin add nightshift@nightshift ``` Review and trust its hooks, then start a new conversation. The [OpenAI Plugin Directory](https://chatgpt.com/plugins/plugins_6a7c58f65d708191b3a705a8625baffe) lists a skills-only edition without the clock-out gate, recovery or usage accounting; turn it off after installing the full plugin. Claude Code: ```text /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](https://cursor.directory/plugins/nightshift) is for discovery. Read the [recovery and CLI limitations](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/how-it-works.md#recovery) before starting a shift. ## First shift Open the project you want Nightshift to change: a Git repository or a persistent folder. Disposable ChatGPT scratch workspaces are not supported. 1. Ask **“Set up Nightshift in this project”** in Codex; use `/nightshift:setup` in Claude Code. Review the proposed checks and permissions. 2. Add one small task under `## Items` in `.nightshift/punch-list.md`, with an outcome and a way to verify it. The [first-shift guide](https://github.com/orwa-mahmoud/nightshift#your-first-shift) has a filled example. 3. Ask **“Start the Nightshift shift”**, or use `/nightshift:start` in Claude Code. Keep this first run attended, then review its changes and receipts before publishing anything. ## Read more - [Why Nightshift exists](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/why-nightshift.md) — the screen and the failures behind the design. - [Choose the work](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/shift-modes.md) — an approved list, a catalog entry, or a goal with a clock. - [Receipts and token usage](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/receipts.md) — progress, measurements, and host limits. - [Archive and continue](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/archive.md) — keep finished history and the next shift's work. - [Real runs](https://github.com/orwa-mahmoud/nightshift/blob/main/examples/README.md). - [Documentation](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/README.md) and [website](https://nightshift.orwamahmoud.com/). Security reporting: [SECURITY.md](SECURITY.md#security-policy). License: [LICENSE](LICENSE).
© Orwa Mahmoud · MIT · hashgraph-online/awesome-codex-plugins