Skip to the figures

Reference architecture · six figures

Architecture

thirdshift turns a GitHub issue into a pull request by running unattended agent sessions against it. The agents write and review the code. Everything else is thirdshift, one deterministic program: it decides what an agent works on, checks its work, and never lets an agent mark its own work ready. These figures show what runs where, who does each step, and where the boundaries are.

Drawn from the manual for the source on main; an installed release may differ. For the same process told step by step, read How thirdshift works.

Figure 1 · the whole system

Agents write the code; thirdshift decides when it counts

An agent session can do anything your user account can, with nobody there to approve it. So every decision that matters is made outside the session, by thirdshift, before the session starts and after it ends. The Day shift is you: you shape the issues and review the pull requests.

The Day shift files issues on GitHub and starts thirdshift, or the operating system’s scheduler starts a Pass. On your machine, thirdshift runs seven deterministic stages: pre-flight checks, the Claim, a Worktree, Delivery, keeping the pull request green, the Self-merge in a Merge run, and cleaning up or failing safely. Inside the Worktree, an agent session on the chosen Harness writes and reviews the code, with Repair sessions when the branch needs work. Every stage that touches GitHub is thirdshift’s, and the pull request goes back to the Day shift for review. DAY SHIFT you Shape the work /grill-with-docs, /to-spec, /to-tickets Run notification email and logs when each Run ends Review the PR or let a Merge run merge it itself YOUR MACHINE ideally a VM with nothing from production on it thirdshift <Issue URL> or merge, architect, pickup … OS scheduler cron or launchd starts Passes pickup · architect · secure thirdshift one Rust binary, deterministic: everything outside the agent’s loop WORKTREE <repo>-issue-<n> Agent session on the Harness: claude, codex, agy, grok, muse or opencode Prompt Session prompt Skills Factory skills Repair · Resume new sessions, same Harness; ≤ 5 Repairs unattended: all your user’s permissions, nobody approves Pre-flight checks Origin match, open issue 1 Claim label the issue in-progress 2 Worktree own checkout, skills in 3 Delivery push, verify PR, ready it 4 Keep it green merge base in, CI, Repair 5 Self-merge Merge run: watched head 6 Clean up, or fail safely Failed run: push, draft 7 GITHUB the shared record Issue or Spec ready-for-agent → in-progress sub-issues: Tickets Issue branch issue-<n> on origin CI checks GitHub Actions Pull request ready for review, merged, or a draft after a Failed run files issues, marks them ready-for-agent pull request, ready for review
Figure 1 The factory. The numbered stages are thirdshift's; only the magenta boxes are agents.
  1. Pre-flight checks stop a Run before anything is created: the Issue URL must match the clone's origin, the issue must be open, and the Base branch must be on origin.
  2. The Claim labels the issue in-progress, so the issue list shows what the factory is working on.
  3. A Worktree gives the Run its own checkout beside your clone, so yours is never touched.
  4. Delivery pushes the branch and checks that the pull request exists and targets the Base branch. thirdshift, not the agent, marks it ready.
  5. Keeping it green merges the Base branch in and watches CI. A conflict or the branch's own red check starts a Repair, at most 5 a Run.
  6. The Self-merge, in a Merge run only, merges exactly the head commit whose CI thirdshift watched.
  7. Cleaning up removes the Worktree. A Failed run pushes its work first and turns the pull request back into a draft.

Figure 2 · thirdshift <Issue URL>

A Run: one issue in, one pull request out

Work reaches a Run as a Ready issue, labelled ready-for-agent. You write most of them, but thirdshift writes some too: an Architect run publishes its plan, a Security run allowed to fix files the fix, and a Base fix files the red CI on the Base branch. One agent session writes, tests and reviews the change, then opens the pull request. A second session reviews it for security, if you ask for that. Then thirdshift checks, pushes and watches.

Ready issues come from the Day shift by hand, or from thirdshift itself: an Architect run publishes a plan, a Security run allowed to fix files a fix issue, and a Base fix files an issue for red CI on the Base branch. You, a Pickup run or the run that filed the issue starts a Run on it. thirdshift prepares the Run with checks, the Claim and a Worktree; an agent session implements, tests, reviews and opens the pull request; thirdshift then delivers it and watches CI. Red CI or a conflict starts a Repair session, at most five per Run; out of Repairs, the Run fails with its work pushed and the pull request back to draft. Otherwise the pull request is left ready for review. YOUR MACHINE ideally a VM with nothing from production on it Day shift you, by hand Architect run publishes a plan Security run files a fix, if allowed Base fix files “CI red on base” file issues, labelled ready-for-agent files one Ready issue labelled ready-for-agent Started by you, a Pickup run, or the run that filed it Prepare checks · Claim · Worktree 1 Agent session /thirdshift-implement /thirdshift-tdd /thirdshift-code-review /thirdshift-pr → PR Deliver push, gh pr ready, merge base in 2 Watch CI own failure or Inherited 3 Repair session conflict or red CI; one Check re-run if unchanged red ≤ 5 Failed run out of Repairs: push work, PR to draft, Claim kept PR ready for review
Figure 2 A Run. The agent writes and reviews the code, but only thirdshift decides the pull request is ready.

Figure 3 · thirdshift merge <Issue URL>

A Merge run: the Run, then thirdshift merges it

The same Run, one step further. Once the pull request is open, ready, mergeable and green, thirdshift merges it with a merge commit, on exactly the head whose CI it watched. Commits someone else pushed to the branch are reviewed first. A required human review still stops it, leaving the pull request ready for you.

A Merge run is a Run that goes one step further. If someone else pushed commits to the Issue branch, a review Repair looks at them first. Once the pull request is open, ready, mergeable and green, thirdshift checks the review decision and merges it with a merge commit on exactly the head whose CI it watched. The issue is closed and its Claim removed. YOUR MACHINE ideally a VM with nothing from production on it Day shift you, by hand Architect run publishes a plan Security run files a fix, if allowed Base fix files “CI red on base” file issues, labelled ready-for-agent files one Ready issue labelled ready-for-agent Started by you, a Pickup run, or the run that filed it Prepare checks · Claim · Worktree 1 Agent session /thirdshift-implement /thirdshift-tdd /thirdshift-code-review /thirdshift-pr → PR Deliver push, gh pr ready, merge base in 2 Watch CI own failure or Inherited 3 Repair session conflict or red CI; one Check re-run if unchanged red ≤ 5 Failed run out of Repairs: push work, PR to draft, Claim kept Foreign commits someone else pushed: a review Repair new Self-merge review gate, --merge --match-head- commit 4 new Merged issue closed, Claim gone
  • new in this workflow
Figure 3 A Merge run. thirdshift merges only code an agent wrote or reviewed, never through GitHub's auto-merge.

Figure 4 · thirdshift <Spec URL>

A Spec run: many Merge runs, one pull request

An issue with sub-issues is a Spec, and its sub-issues are Tickets. Each Ticket gets its own Merge run, not into main but into the Spec branch, in the order GitHub's “blocked by” links allow. Independent Tickets run at once, each in its own Worktree. The Spec ends as one pull request for you to review.

A Spec is an issue whose sub-issues are Tickets. Each Ticket gets its own Merge run into the Spec branch, in the order its blocked-by links allow. One session then reviews the whole Spec branch against the Spec, thirdshift delivers it and watches CI, and the Spec ends as one Spec PR ready for review. YOUR MACHINE ideally a VM with nothing from production on it Spec an issue with sub-issues Ticket a · Merge run blocked by nothing new Ticket b · Merge run blocked by a Ticket c · Merge run blocked by a and b Spec branch each Ticket’s PR merged in; draft Spec PR, checklist Spec review one session reviews the whole branch against the Spec new Deliver + CI Spec PR ready A failed Ticket stops the Tickets that depend on it. The Spec carries the Claim; its Tickets make none.
  • new in this workflow
Figure 4 A Spec run. Many Merge runs land on a Spec branch, and one Spec PR reaches the Day shift.

Figure 5 · thirdshift pickup, architect, secure

The Passes: the factory finds its own work

A Pass takes no Issue URL, so your operating system's scheduler can start it; thirdshift never schedules itself. Only one Pass runs on a repository at a time, and a Pass with nothing to do is skipped, not failed. Architect and Security runs wait while a Ready issue is open, so work you shaped goes first.

The operating system’s scheduler starts three kinds of Pass, each taking no Issue URL. A Pickup run sweeps closed issues, respects the Claim limit and runs the lowest-numbered Ready issue. An Architect run reviews the architecture and either publishes a plan, which it builds with a Run or Spec run, or files an idea for the Day shift to triage. A Security run audits the Base branch, runs target code to reproduce what it finds, records each finding privately and, when fixing is allowed, files a fix issue and runs it. Running target code is why the Security run needs an OS sandbox, which is proposed but not built. YOUR MACHINE results leave only as GitHub issues, PRs and private advisories OS scheduler cron, launchd new Pickup run Sweep, Claim limit, then the lowest Ready issue Run Figure 2 Architect run an Architecture review finds the top idea Architect plan ready-for-agent Architect idea needs-triage, for you Run or Spec run Figures 2 to 4 needs an OS sandbox · proposed Security run audits the Base branch; runs code to reproduce Security finding recorded privately: advisory or issue Security fix if allowed: files an issue and runs it Fencing: on a schedule, with fixing allowed
  • new in this workflow
  • proposed, not built
Figure 5 The Passes. The factory finds Ready issues, architecture plans and vulnerabilities by itself.

Figure 6 · from the outside in

Containment: where the boundaries are

thirdshift draws no security boundary around its agents: every session can do what your user account can. So containment comes from where you run it. The boundary that holds is the machine: best a virtual machine with nothing from production on it. An OS sandbox inside it, for the code an agent runs, is proposed but not built.

Nested boundaries around an agent session, from the outside in: your machine, ideally a virtual machine with nothing from production on it; your user account, whose permissions and logins every session has; the Worktree, which keeps checkouts apart but is not a security boundary; and, proposed but not built, an OS sandbox inside it for the target code an agent runs. Work leaves the machine only to GitHub and to the model provider. YOUR MACHINE ideally a VM with nothing from production on it YOUR USER ACCOUNT every session has all its permissions, sudo too thirdshift starts every session Logins gh, git, Harness: any session can read and use them Logs sessions, audits WORKTREE keeps checkouts apart; not a boundary Agent session Harness sandbox and approvals off (ADR-0013); Claude Code’s auto mode screens risky actions OS SANDBOX bubblewrap + AppArmor, or Podman proposed · #726 #608 #398 target code would run here: builds, tests, proofs of concept, with no network and scratch-only writes would run code in GitHub pushes, PRs, labels, private advisories: the work leaves here Model provider API prompts, and the code quoted in them, leave the machine here git, gh HTTPS
  • your machine
  • enforced by the OS
  • keeps things apart, not security
  • proposed, not built
Figure 6 Containment. Your machine is the boundary that holds; an OS sandbox is the proposed wall inside it.
Your machine
holds · your setup Keep production data, keys and unrelated logins off it, and assume a session can read or change anything on it.
Your user account
enforced, but shared It separates thirdshift from other users, not from its own sessions: a session can read the gh and git logins and push with them (#691).
The Worktree
not a security boundary It keeps your checkout and other Runs apart. Every Harness runs with its own sandbox and approvals off (ADR-0013). Claude Code's auto mode screens risky actions, but enforces no boundary.
An OS sandbox
proposed A second wall inside the machine, for the code an agent runs: no network, writes only to scratch space, a dummy home directory. On Ubuntu 24.04, bubblewrap needs an AppArmor profile that lets it create user namespaces. Tracked in #726 (a runner), #608 (a setup check) and #398 (sandboxed Codex).

Next: what an unattended session can do, How thirdshift works step by step, or every prompt and skill the agents get.