NIGHT PORTER

The whole shift, start to finish

How it works

From the moment you switch it on to the reply on your PR: every state Night Porter can be in, and who decides what happens next. Amber boxes wait for you.

Night Porter’s whole shift, as a state diagramSetup, then start. On watch it polls the forges. Each event goes through intake: dropped, held in the inbox, or passed on. Dispatch debounces, checks the schedule and the caps, and queues one job per PR. The job runs in its own worktree, then pre-push checks. By level: observe and suggest post nothing, draft waits for your approval, auto pushes. Then it notifies you and goes back on watch. Pause, resume and stop are side states, and handoff is a side exit to your own terminal. The numbered list below the diagram says the same in words.1Check inSETUPnightporter setup: accounts and tokensfinds your clones under code_dirnightporter subscribe owner/nameOff dutySTOPPEDstop, Ctrl-C or SIGTERM:a clean shutdown,nothing half-done pushedstart brings it backnightporter start (or the service)2On watchWATCHINGpolls notifications every poll_intervaland your open GitLab MRssweeps open PRs for conflicts and red CIno webhooks, nothing to hoststopPausedno new jobs start,running ones finishp or nightporter pausepauseresumesomething lands on a PR3At the doorINTAKEnot subscribed, trigger off, your owncomment or a denied author: droppedmaintainer asks (label, /nightporter,nightporter sweep) need maintainer modeInboxan unknown authorwaits for you:allow, or ignorenewallowtrusted4The queueQUEUEDwaits for the PR to go quiet (debounce)inside a schedule window? if not, it waitsone job per PR, with everything new on itdaily cap, CI-attempt cap, concurrencyyour own PRs first, sweeps never hog ita slot opens5On the jobRUNNINGits own git worktree, your checkout untouchedDDEV or Docker up, if the repo needs ityour agent runs, sandboxedplus any review steps from packsRun approvalNEEDS YOUsomeone else’s code?it waits for your OKbefore it runs a thingtheirsOK6Bag checkPRE-PUSHsecrets, protected files, dependencies,diff size, history rewritesthe blocking ones can’t be turned offHeldBLOCKEDa check fails:nothing leavesuntil you lookfail7 · BY LEVELobservepings you.that’s all.suggestcommits locally,hands you a replyto paste. Postsnothing.draftwaits for you.a approves,x dismisses:nothing posted.autopushes andreplies on itsown. Checksstill apply.approvedOut the doorPUSH + REPLYNight Porter pushes and replies,not the agent. Never a force-push.8Ring the bellNOTIFYdesktop, Slack, Discord, ntfy, a webhookor your own command. Then back on watch.It never merges, closes or approves.back on watch9HandoffSIDE DOORpress h on a job: itsworktree opens in herdr,Rex, tmux, Zellij or aterminal, agent briefed.Claude, Codex, pi, Cursor,Copilot, Goose, Qwen,Droid, Kiro…h

The same, in words

  1. 1

    Check in

    nightporter setup connects your accounts (tokens from gh, glab, tea or your keychain) and finds your clones under code_dir. Subscribe the repos it should watch, then nightporter start, or let launchd or systemd run it.

  2. 2

    On watch

    Every poll_interval it checks GitHub and Forgejo/Gitea notifications and your open GitLab MRs, and every sweep_interval it looks over your open PRs for merge conflicts and red CI. No webhooks. nightporter pause stops new jobs (running ones finish) until resume. nightporter stop, Ctrl-C or SIGTERM shut it down cleanly.

  3. 3

    At the door

    Repos you didn’t subscribe, triggers you switched off, your own comments and denied authors are dropped. Trusted people go through. Anyone unknown waits in the inbox until you allow or ignore them. Maintainer requests (a label, /nightporter fix and friends, or nightporter sweep) need maintainer mode.

  4. 4

    The queue

    It waits for the PR to go quiet (the debounce) and for a schedule window. Everything new on a PR becomes one job, within the daily cap, the CI-attempt cap and the concurrency limit. Your own PRs go first, and sweep jobs never use the last quarter of the daily cap.

  5. 5

    On the job

    A git worktree of its own, so your checkout stays put. DDEV or Docker if the repo needs them, then your agent (Claude Code, OpenCode, Codex or Gemini CLI) runs sandboxed, plus any review steps from packs. Someone else’s code waits for your OK before it runs.

  6. 6

    Bag check

    Secrets, protected files, dependency changes, diff size and history rewrites. The blocking checks can’t be turned off, and a failed one holds the push until you look.

  7. 7

    By level

    observe pings you. suggest commits locally and hands you a reply to paste. draft waits for you: a in the TUI, nightporter approve or a /nightporter approve comment, or x to dismiss it with nothing posted. auto pushes and replies on its own.

  8. 8

    Ring the bell

    A desktop ping, Slack, Discord, ntfy, a webhook or your own command. Then it’s back on watch. It never merges, force-pushes, closes or approves.

  9. 9

    The side door

    Press h (or nightporter handoff <id>) on a finished or waiting job and its worktree opens in herdr, Rex, tmux, Zellij or a terminal, with an agent already briefed: the one that ran the job, or Claude, OpenCode, Codex, Gemini, pi, Cursor, Copilot, Goose, Qwen, Droid or Kiro (handoff_agent).

Every setting named here is in the configuration reference.