Queue coding plans during the day, approve them, execute later in isolated worktrees, and inspect reports. Background agentic execution requires an explicitl...
---
name: night-shift
version: 1.0.5
description: "Queue coding plans during the day, approve them, execute later in isolated worktrees, and inspect reports. Background agentic execution requires an explicitly configured non-interactive runner."
metadata:
{
"openclaw":
{
"requires": { "bins": ["python3", "git"] },
"optional":
{
"bins": ["agent", "cursor", "claude"],
"env":
[
"OPENCLAW_WORKSPACE",
"NIGHT_SHIFT_DATA_DIR",
"NIGHT_SHIFT_MODEL",
"CURSOR_CLI",
"CURSOR_API_KEY",
"TELEGRAM_BOT_TOKEN",
"TELEGRAM_CHAT_ID",
"NIGHT_SHIFT_CHAT_ID",
],
},
"capabilities":
[
"filesystem-read-write",
"git-worktrees",
"subprocess-execution",
"optional-cursor-cli",
"optional-claude-cli",
"optional-telegram-notifications",
"optional-model-provider-calls",
],
},
}
---
# Night Shift
Night Shift is an autonomous queued-execution skill for engineering work.
Instead of asking the agent to do one large coding task immediately, you build a queue of plans, review or approve them, then run them in a controlled batch window. Each plan is split into phases, executed in isolation, verified, checkpointed, and summarized in a report.
**Mental model:**
- Daytime: create and refine plans
- Before execution: approve what is safe to run
- Execution window: Night Shift runs plans phase by phase
- Morning: inspect results, merge, retry, or continue
This is useful when you want:
- deferred execution instead of immediate chat-time work
- safer batching for multi-step changes
- isolated worktrees per plan
- retry and checkpoint behavior
- a written report after execution
---
## When to Use
Use Night Shift when the user asks for things like:
- “good night”
- “queue this for later”
- “plan add …”
- “run these approved plans overnight”
- “night shift status”
- “show my morning report”
- “retry plan #3”
- “merge that finished plan”
Prefer Night Shift over immediate execution when:
- the work is multi-phase
- the task needs isolation from the main repo state
- the user wants review/approval before execution
- the work may take a long time
- you want a queue of tasks rather than one interactive run
Do **not** use Night Shift for:
- tiny one-off edits better handled immediately
- high-risk production actions without review
- tasks that require constant human decisions mid-run
- public/external actions that should be explicitly approved in the moment
---
## Core Concepts
### 1. Plan
A plan is the unit of queued work. It includes:
- title
- optional description
- optional repo URL
- priority
- token/time budget hints
- generated phases
- status and execution metadata
### 2. Phase
Each plan is split into phases. A phase has:
- a title
- a prompt/instruction
- an execution method
- verification settings
- retry state
- status
### 3. Execution Method
Each phase chooses one of several execution methods:
- `shell`
- `cursor`
- `claude-code`
- `subagent`
This lets the framework mix deterministic shell work with agentic coding work.
### 4. Worktree Isolation
Each plan runs in its own git worktree under `data/night-shift/worktrees/`.
That means Night Shift can:
- avoid trampling the main branch
- keep plan-specific diffs separate
- retry or inspect work in isolation
- support safer merge/rollback flows
### 5. Verification
Phases can be checked after execution using one of several verification modes, including:
- `files_exist`
- `check_git_diff`
- `run_tests`
- `lint_check`
- `smoke_test`
- `import_check`
- `integration_check`
- `snapshot_diff`
- `none`
### 6. Reporting
After execution, Night Shift writes a report so the next interaction starts from evidence instead of guesswork.
---
## Typical Workflow
### During the day
1. Add one or more plans
2. Review phases
3. Edit prompts or priorities if needed
4. Approve the plans that are safe to run
### At execution time
5. Start Night Shift
6. It acquires a lock, checks budgets, creates worktrees, and executes phases
7. It verifies each phase, checkpoints progress, records failures, and logs results
### After execution
8. Read the report
9. Inspect worktrees or diffs
10. Merge successful work, retry failed work, or queue follow-up plans
---
## User-Facing Commands
These are the command patterns the skill is designed around.
| Command | Purpose |
|---|---|
| `plan add <desc>` | Create a new plan with generated phases |
| `plan steal <url> <desc>` | Queue work derived from an external repo/project |
| `plan list [status]` | Show plans in the queue |
| `plan show #<id>` | Show full details for one plan |
| `plan approve #<id>` | Approve one plan |
| `plan approve all` | Approve all queued plans |
| `plan remove #<id>` | Remove a plan |
| `plan priority #<id> <level>` | Change priority |
| `plan edit #<id> phase <n> prompt <text>` | Refine a phase prompt |
| `good night` | Start execution of approved plans |
| `night shift status` | Show current state |
| `night shift stop` | Request stop / halt execution |
| `night shift dry-run` | Preview what would execute |
| `morning` | Show the latest execution report |
| `night shift merge #<id>` | Merge completed plan results |
| `night shift inspect #<id>` | Inspect outputs/worktree |
| `night shift retry #<id>` | Retry a failed or partial plan |
If your host agent uses a different natural-language wrapper, preserve the same intent and lifecycle.
---
## Architecture
Night Shift is split into a few major parts.
### Queue and Models
- `models.py` — core plan/phase data models and enums
- `queue.py` — CRUD, queue index, plan storage, approvals, updates
- `phase_generator.py` — creates initial phases from plan input
### Execution Engine
- `executor.py` — main run loop, orchestration, locking, budget checks, reporting
- `phase_runner.py` — executes individual phases using the chosen method
- `subagent_runner.py` — helper for subagent-based execution
### Safety and Recovery
- `verifier.py` — phase verification logic
- `checkpoint.py` — save/resume progress
- `failure_memory.py` — track known failures and avoid blind repetition
- `lock.py` — prevent overlapping runs
- `budget.py` — per-phase/per-plan/night budget tracking
- `memory_guard.py` — watchdog for memory/process hygiene
### Repo / Git Operations
- `git_manager.py` — worktree setup, commit/reset helpers
### Visibility and Operations
- `reporter.py` — morning-style summaries
- `monitor.py` — notifications and health checks
- `watchdog.py` — execution monitoring
- `status.py` — status helpers
- `cron_trigger.sh` / `ns-control.sh` — optional shell wrappers
### Optional Extensions
The `bmad_*.py` files are advanced helpers for richer planning/PRD flows. They are **not required** for the core Night Shift lifecycle.
---
## Execution Flow
A typical run looks like this:
1. **Preflight**
- confirm no conflicting lock
- load queue
- check for approved plans
- initialize budget / logs / monitors
2. **Plan selection**
- choose approved plans in queue order / priority order
3. **Per-plan setup**
- create or prepare isolated worktree
- load checkpoint if resuming
4. **Per-phase execution**
- build phase prompt
- dispatch via the selected execution method
- capture output, status, timing, and any token/cost metadata available
5. **Verification**
- run configured verification step
- mark success/failure
- record failure memory if relevant
6. **Persistence**
- update plan JSON
- update queue index
- save checkpoint/logs
7. **Completion**
- finalize plan status
- generate report
- release lock
---
## Safety Model
Night Shift is designed to be agentic, but not reckless.
### Safety features
- **approval gate** before execution
- **worktree isolation** per plan
- **execution lock** to prevent overlapping runs
- **phase-by-phase progression** instead of one giant opaque run
- **verification hooks** after phases
- **checkpointing** for resumes/recovery
- **failure memory** to reduce repeated mistakes
- **budget caps** across phase/plan/night scopes
- **watchdog/monitoring** support
### What this protects against
- clobbering the main branch
- executing multiple Night Shift loops at once
- losing progress on interruption
- repeating the same failing step forever
- oversized unattended execution sessions
### What it does **not** guarantee
- perfect code quality
- correct architectural judgment for every task
- safe production deployment by default
- zero hallucination from external coding models
You still need sensible approval and review.
### Trust, permissions, and security scanners
Night Shift may be flagged by automated scanners because it intentionally includes operational automation primitives:
- shell wrappers (`cron_trigger.sh`, `ns-control.sh`, `claude-wrapper.sh`)
- Python subprocess execution for approved phases
- git worktree, commit, reset, and diff helpers
- optional Cursor CLI / Claude Code / subagent dispatch
- optional Telegram notification support
These are expected for an unattended coding workflow, but they deserve review before use. Night Shift does **not** bundle private keys, hidden credentials, miners, persistence malware, or background network beacons. It only uses credentials and CLIs already available in the host environment.
Before running it in a new workspace:
1. Review queued plans and phase prompts before approval.
2. Run `night shift dry-run` first when available.
3. Start with a disposable test repo or branch.
4. Keep production deploys as explicit manual steps unless you intentionally add deploy phases.
5. Inspect diffs/reports before merging completed work.
For non-interactive ClawHub installs, some registries may require `--force` after scanner warnings. Treat that as a prompt to review the code, not as a failure signal.
---
## Storage Layout
Night Shift stores runtime state under:
```text
data/night-shift/
├── queue.json
├── plans/
├── worktrees/
├── execution/
├── reports/
├── failure-memory.json
├── budget.json
└── execution.log
```
### Important files
- `queue.json` — lightweight queue index
- `plans/*.json` — full plan records
- `worktrees/<plan_id>/` — isolated git worktree per plan
- `failure-memory.json` — prior failed step fingerprints
- `budget.json` — current budget tracking
- `execution.log` — main execution log
---
## Environment Variables
Night Shift now supports portable configuration instead of relying on hardcoded local paths.
### Core
- `OPENCLAW_WORKSPACE` — override workspace root
- `NIGHT_SHIFT_MODEL` — preferred model hint for model-driven helpers
- `CURSOR_CLI` — explicit path to Cursor CLI / `agent` binary
### Notifications
- `NIGHT_SHIFT_CHAT_ID` — target chat for Night Shift notifications
- `TELEGRAM_CHAT_ID` — fallback notification target
- `TELEGRAM_BOT_TOKEN` — Telegram Bot token for notifications
### Execution environment
Night Shift also inherits normal environment from the host runtime, including anything needed by:
- git
- Python
- shell commands
- coding harnesses / subagents
If a specific execution method requires additional auth or binaries, document that at the host level.
---
## Prerequisites
### Required
- Python 3
- git
- workspace write access
- ability to create and modify files in `data/night-shift/`
- a host environment that can run shell commands and Python scripts
### Optional but useful
- Cursor CLI / agent binary for `cursor` execution
- Claude Code for `claude-code` execution
- subagent support for delegated runs
- Telegram bot setup for notifications
### Strongly recommended
- run inside a git-backed workspace
- use approval before unattended execution
- keep tests/lint scripts working in the target repo
---
## Examples
### Example 1 — queue a feature for later
User intent:
> Add OAuth login to the app, but do it overnight.
Night Shift flow:
1. `plan add add OAuth login to the app`
2. inspect generated phases
3. `plan approve #<id>`
4. later: `good night`
### Example 2 — multiple plans in one batch
User intent:
> Queue three fixes now, run them all tonight.
Flow:
1. add three plans
2. set priorities as needed
3. approve the safe ones
4. run Night Shift
5. read the morning report
### Example 3 — dry run before execution
User intent:
> Show me what would run tonight.
Flow:
- `night shift dry-run`
### Example 4 — retry a failed plan
User intent:
> Retry the failed parser plan.
Flow:
- inspect plan/report
- refine the phase prompt if needed
- `night shift retry #<id>`
### Example 5 — inspect before merge
User intent:
> Show me what Night Shift changed before we merge.
Flow:
- `night shift inspect #<id>`
- review diff/worktree/tests
- `night shift merge #<id>` when satisfied
---
## How to Operate the Skill Well
### Good plan inputs
Night Shift works best when the plan title/description is concrete.
Better:
- “Add retry logic to payment webhooks and verify with integration tests”
- “Refactor dashboard query caching and run frontend smoke tests”
Worse:
- “make it better”
- “fix the app somehow”
### Good approval policy
Approve unattended runs when:
- the repo is in a sane state
- the task is scoped
- verification exists
- you can tolerate isolated failures
Avoid approval when:
- the task is ambiguous
- the run might touch production systems directly
- the work needs live stakeholder decisions
### Good execution method selection
Use:
- `shell` for deterministic scripted work
- `cursor` / `claude-code` for coding-heavy phases
- `subagent` for delegated structured work
---
## Limitations
Be honest about these.
- It is not a general scheduler for arbitrary business processes.
- It is optimized for engineering work in a writable workspace.
- Quality depends heavily on phase quality and verification quality.
- If the underlying coding harness is weak or unavailable, outcomes degrade.
- Worktree-based isolation assumes the repo supports normal git operations.
- Some wrapper scripts and helpers are host-environment dependent.
- Long unattended runs still need human review before high-trust deployment.
---
## Troubleshooting
### “No approved plans found”
Approve at least one plan before starting execution.
### “Night Shift already running”
A lock file or active run exists. Inspect status before forcing a restart.
### “Worktree creation failed”
Check:
- git repo health
- branch/worktree permissions
- existing conflicting worktrees
### “Phase keeps failing”
- inspect the plan’s phase prompt
- review verification settings
- check failure memory / logs
- reduce scope and retry
### “Notifications are not sent”
Check notification env vars:
- `TELEGRAM_BOT_TOKEN`
- `NIGHT_SHIFT_CHAT_ID` or `TELEGRAM_CHAT_ID`
### “Cursor / Claude execution not found”
Set the expected binary path explicitly or install the required tool:
- `CURSOR_CLI`
- whichever CLI your host maps to `claude-code`
### “Execution stopped midway”
Inspect checkpoints, report output, logs, and plan status. Resume/retry instead of starting from scratch blindly.
---
## Publishing Notes
Night Shift is publishable as a **power-user engineering skill**.
Its strongest differentiators are:
- queued plan lifecycle
- isolated worktrees
- phase verification
- checkpointing and retry behavior
- morning-report workflow
Its biggest adoption caveats are:
- requires a repo-aware writable environment
- works best with supporting CLIs/tools already installed
- more operational than a simple one-file prompt skill
That is fine. Don’t oversell it as “plug-and-play for everyone.” Sell it as a serious autonomous coding workflow for advanced users.
---
## Files
Core engine files in `scripts/` include:
- `models.py`
- `queue.py`
- `phase_generator.py`
- `executor.py`
- `phase_runner.py`
- `verifier.py`
- `checkpoint.py`
- `failure_memory.py`
- `budget.py`
- `git_manager.py`
- `lock.py`
- `reporter.py`
- `monitor.py`
- `watchdog.py`
- `subagent_runner.py`
- `memory_guard.py`
Optional/advanced helpers:
- `bmad_batch.py`
- `bmad_context.py`
- `bmad_guardrails.py`
- `bmad_phases.py`
- `bmad_prd_evolve.py`
- `bmad_queue.py`
- `bmad_rollback.py`
Shell helpers:
- `cron_trigger.sh`
- `ns-control.sh`
- `claude-wrapper.sh`
---
## See Also
- `REFERENCE.md` — operational reference, setup notes, environment variables, and troubleshooting
- `scripts/test_queue.py` — queue behavior checks
- `scripts/test_integration.py` — end-to-end integration checks
don't have the plugin yet? install it then click "run inline in claude" again.