* . . . * . +
_ _ _ _ _ ____ _ _ __ _ *
| \ | (_) __ _| |__ | |_ / ___|| |__ (_)/ _| |_ .
| \| | |/ _` | '_ \| __| \___ \| '_ \| | |_| __| (
| |\ | | (_| | | | | |_ ___) | | | | | _| |_ *
|_| \_|_|\__, |_| |_|\__| |____/|_| |_|_|_| \__|
* |___/ . + . *
Long-running unsupervised agent framework
A batch processing framework for AI agents. Define a table of items, write task instructions, and let a manager-plus-dev system work through them autonomously with built-in retries, self-improvement, and self-validation.
Nightshift runs inside Claude Code as a manager subagent that dispatches dev work as fresh top-level claude -p subprocesses. Dev subprocesses inherit your full user-level MCP configuration — any MCP you've installed in Claude Code (Slack, Drive, Playwright, internal company MCPs) is automatically available to every Nightshift task. Nightshift is distributed as a Claude Code plugin via its own marketplace.
How It Works
A shift is a batch job. It contains a CSV table of items to process and one or more task definitions that describe what to do with each item. Two roles collaborate to execute the work:
- Manager (a Claude Code subagent) -- reads shift state, picks the next item, dispatches dev work as a
claude -p subprocess via the bundled dispatch-batch.sh helper, applies step improvements from successful dev runs (unless disable-self-improvement: true is set), and reports progress. Writes manager.md and task files; reads table.csv for status information.
- Dev (a fresh top-level Claude session per item) -- executes task steps on a single item, self-validates, retries up to 3 times, reports step improvement recommendations (unless self-improvement is disabled), and writes its own status to
table.csv (done on success, failed on failure). Because each dev runs as a top-level claude -p subprocess, it sees every user-configured MCP without any Nightshift-specific setup.
Each item-task moves through a state machine:
todo --> done
\
-> failed
Prerequisites
- Claude Code v2.1.83 or later (for
--permission-mode auto; see the Permission mode section for the fallback path on older versions or non-eligible plans).
- qsv CSV toolkit (required) -- install via
brew install qsv or download from GitHub releases for non-Homebrew platforms
- flock file locking utility (required) -- install via
brew install flock or use the version bundled with util-linux on Linux
- jq JSON processor (required by
dispatch-batch.sh) -- install via brew install jq
Installation
Inside Claude Code, add the marketplace and install the plugin:
/plugin marketplace add johndaskovsky/nightshift
/plugin install nightshift@nightshift
After install, restart Claude Code if it's already running (so the new skills are discovered), then verify your system has the required dependencies:
/nightshift:doctor
The doctor skill checks for qsv, flock, and jq on PATH. It prints brew install hints for any that are missing.
You're ready when /nightshift:doctor reports all three present. Move on to Quick Start.
Permissions
Nightshift's skills declare the Bash commands they need (qsv, flock, claude, jq) via allowed-tools frontmatter. Claude Code should honor these declarations automatically. If you see repeated permission prompts during a shift, add the entries to ~/.claude/settings.json once:
{
"permissions": {
"allow": ["Bash(qsv *)", "Bash(flock *)", "Bash(claude *)", "Bash(jq *)"]
}
}
Updates
Marketplaces auto-update on Claude Code startup. To pull the latest plugin version manually:
/plugin marketplace update
Deprecated: npm CLI
Earlier Nightshift versions (1.x–3.x) shipped as the npm package @johndaskovsky/nightshift with a nightshift init command. This path is deprecated as of 4.0.0. The npm package still exists but nightshift init only prints these instructions and exits. Migrate to the plugin install path above.
If you have a previous project-local install (<project>/.claude/skills/nightshift-*/), it will shadow the plugin via Claude Code's skill precedence. Delete those directories from your projects to let the plugin take over. Your .nightshift/<shift>/ data is unaffected.
Quick Start
All commands run inside Claude Code.
