Project
Nightshift FAQ
Direct answers about autonomous shifts, Cursor, safety, recovery, non-Git work, installs, platforms, commits, and the clock-out gate.
Updated
What is Nightshift, in short?
Nightshift is a local-first, MIT-licensed plugin that gives Cursor, Codex, and Claude Code a durable work contract, optional mechanical rules, recovery, and reviewable receipts. It can work in repositories or persistent artifact folders without replacing tests, review, or host permissions.
Core questions
These are the short answers people usually need before trying a first shift.
- Nightshift works from a punch list or a catalog shift composed from your sentence.
- The state stays in the project’s private .nightshift workspace.
- Commits are local by default and pushes are explicit.
- The owner can stop the shift at any time.
- The first run should be attended.
Trust boundary
The clock-out gate enforces that approved boxes are not quietly abandoned. It does not independently prove that a checked item is correct. Good definitions of done, project gates, and human review remain essential.
Start with a bounded prompt
This prompt names the outcome and preserves Nightshift’s review boundary. Paste it into the supported coding host from the project you want to change.
Answer my questions about Nightshift using only the released product behavior and link me to the relevant evidence.What this workflow does not claim
- Nightshift does not replace project tests, host permissions, or human review.
- Support is claimed only for the verified hosts and environment boundaries documented in the repository.
Evidence and sources
These links support the released behavior, public outcomes, or problem language described on this page.
Frequently asked questions
What is Nightshift?
Nightshift is an open-source plugin for accountable, time-bounded coding shifts in Cursor, Codex, and Claude Code.
Does Nightshift support Cursor?
Yes. Nightshift ships a native Cursor plugin with skills, hooks, persistent shift state, and conservative recovery. Cursor IDE Agent and Cursor CLI use different conversation stores, so recovery preserves the contract without pretending a CLI worker is the same IDE chat.
Can Nightshift work without a Git repository?
Yes. A persistent folder can use artifact mode for compatible research, documentation, SEO, and writing shifts. Completed items leave local receipts instead of commits; disposable scratch workspaces remain unsupported.
Does Nightshift keep working after context compaction?
Yes. The authoritative punch list, decisions, and progress live on disk, so the contract survives compaction and controlled recovery.
Can Nightshift run without a prepared backlog?
Yes. Give Hunt a sentence and the hours. It inspects the project, composes the catalog work that serves that objective, and either waits for review or runs directly when the sentence already says so.
Does Nightshift push code?
Not by default. It creates local commits for review; pushing requires explicit authorization in the shift contract.
Can I stop a shift?
Yes. Use the host Stop command or create the .nightshift/STOP file. Unfinished items remain open.
Claude Code died overnight with API Error 500 or 529 Overloaded — does the run resume automatically?
Yes. The night watchman detects the dead session, waits out the outage on its interval, and revives the same recorded conversation with the punch list intact.
What stops an overnight shift from eating my whole API allowance?
Your plan's limits are the hard ceiling — Nightshift runs inside an ordinary session. Open-ended shifts take an explicit hour budget, checklist shifts end when the last box is ticked, and the contract is written before the run.
Does the clock-out gate prove the implementation?
No. It enforces the declared completion contract. Project checks and human review establish whether the implementation is correct.
Which platforms are supported?
macOS and Linux use the bundled shell runtime. Native Windows uses bundled PowerShell. WSL is supported as a Linux environment when all components stay in one distribution.
Is Nightshift a hosted service?
No. It is a plugin with local project state; no separate server or Nightshift API key is required.
Can the agent run sudo, docker run, or brew install during a shift?
Not unless you allow it. Five elevation categories are denied out of the box and can be allowed per category for one shift or permanently. Reads such as docker ps are not gated.
How do I know what a shift cost?
Each item's receipt carries the tokens and time the runtime measured from the host's own records. Nothing is estimated, and a figure the host does not report reads unavailable.
Can Nightshift start a shift on a schedule?
Yes. Schedule preflights the queued work and permissions, then prints the launchd, cron, systemd, or Task Scheduler entry and its install command. It registers nothing itself, and the generator needs no model session.
What happens to the files after a shift?
The gate writes a morning receipt, and Archive files ticked items, logs, handled snags, and answered decisions under a dated folder when you ask. Filing copies; retention deletes only on an explicit yes.
Does Nightshift require Python?
No. The plugin ships shell and PowerShell only. Hooks read the rules file with a bundled reader, and native Windows uses PowerShell's built-in JSON parser.