Night Shift

⚡ When to Use

💡 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 # 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 #

Example 5 — inspect before merge

User intent: > Show me what Night Shift changed before we merge.

Flow:

night shift inspect #

review diff/worktree/tests

night shift merge # when satisfied

---

⚙️ Configuration

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

---

📋 Tips & Best Practices

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

---