Factory: local setup

How to run Rose tickets on your Mac with Night Shift's local factory. For the architecture, see Factory.

Prerequisites

• gh logged in with push access to inboundx/inboundx (delivery pushes and opens PRs as you), and git able to clone it.
• claude and/or codex installed and logged in.

Set up the Mac

npx nightshift-factory setup \
  --repository inboundx/inboundx \
  --bootstrap "python3.12 ./bootstrap.py --branch" \
  --venv backend/.venv \
  --verify "just --justfile backend/justfile test"

You sign in with GitHub in your browser. --bootstrap gives each worktree its own Supabase preview branch, never a shared database. --verify commands must pass on the delivered commit; choose fast checks that cover what the route's tickets change. Running setup again keeps the same machine and service.

Setup installs a launchd service and a ☾ menu-bar item that start at login. If macOS hides the ☾ item, allow Python in System Settings, Menu Bar.

Connect Linear and route it

Setup opens Night Shift's Settings, Assigned issues (also Assigned issues settings… in the ☾ menu):

1. Connect Linear once; a Linear admin approves Night Shift as an assignee.
2. Choose inboundx/inboundx, your Mac, develop as the branch PRs go into, and who may assign it work.
3. Save and enable, once the old owners of this work have stopped (see the cutover plan).

Use from Linear

Assign an issue to Night Shift, or @-mention it. The Mac creates ~/.nightshift/local/workspaces/inboundx__inboundx/<ISSUE>, runs the engine, then verifies, pushes nightshift/<issue> and opens the PR into develop. Reply in the same session to correct it; Stop stops it.

Local files

Path	Purpose
~/.nightshift/local/config.json	Night Shift URL, machine id, repositories and their trusted commands
Keychain item nightshift-local	The machine's Night Shift credential
~/.nightshift/local/runtime/<version>/	The installed runtime the service runs
~/.nightshift/local/workspaces/	Per-issue worktrees, kept across attempts
~/.nightshift/local/attempt.json	The running attempt, for recovery after a crash
~/.nightshift/local/logs/	Service logs

Troubleshooting

Symptom	Fix
Nothing starts	nightshift-local status says why: route idle or paused, app not installed, or a machine problem (gh or engine not logged in).
The issue says interrupted twice	Check the branch, then nightshift-local work <id> resume (or close).
The Mac is gone for good	Confirm it no longer writes to the branch, then nightshift-local abandon <attempt>.
Setup refuses to replace the service	An attempt is running; wait for it, or pass --force.