Unattended Claude Code agents for your ticket backlog.

  1. a ticket
  2. its own sandbox
  3. a second agent reviews
  4. your lint, tests, build
  5. your local branch

Queue tickets, start a run and read the report in the morning. Nothing is pushed until you push it.

$ git clone https://github.com/henkisdabro/sandcastle-kit.git ~/sandcastle-kit && cd ~/sandcastle-kit && pnpm install && ./bin/sandcastle setup

DRY_RUN=1 sandcastle run the first time: it implements, reviews and gates your tickets, and merges nothing.

macOS (OrbStack or Docker Desktop) or Linux (rootful Docker Engine), Node 22.18+, and a Claude subscription or API key.

A run, as the status view shows it

An example night, played back as sandcastle status shows it: thirteen tickets, nine merged, two left for you, two waiting on those.

  • Ticket 41, rate limiting: implemented and reviewed, failed its tests, repaired, reviewed again, merged.
  • Tickets 42, 43, 45, 48, 49, 52 and 53: implemented, reviewed, gates green, each merged as it went green while the others worked.
  • Ticket 44, a date library upgrade: still failing three tests after two repairs; left for you.
  • Ticket 46: gates green, but it changes CI config, so it is held for you to merge by hand.
  • Ticket 47: waited for ticket 41; once that landed, it started in a free sandbox in the same run, and was implemented, reviewed and merged.
  • Tickets 50 and 51 wait for 44 and 46 to close.
  • By morning: nine branches merged into the local main branch, none of it pushed.

A real run: the kit, on its own backlog

The kit is built by its own runs. This is one of them, on 4 October 2026, from the run record. Every ticket is a public issue you can open.

tickets
18
merged
18
left open for a person
2, a criterion unmet
wall clock
1 h 40 min
tokens
28.4M in / 343k out
models
Sonnet 5.5 implements, Opus 5.5 reviews
sandboxes
5 at once
  1. #252Size: a read-only sandcastle size command that recommends the pool's limits25m1.9M / 25k
  2. #249The gates phase time includes the wait for a machine-wide gates slot16m1.4M / 14k
  3. #244A green resolution held by the stray-path check reports 0 commits and no gates22m1.9M / 14k
  4. #258backup-size test fails intermittently: 2 packs after a drop, not 131m1.0M / 20k
  5. #251An ended run's status view shows the next run's settings beside the report's recorded ones18m1.1M / 12k
  6. #250One ticket can spend an hour and 19M tokens with no ceiling short of idle15m878k / 10k
  7. #248The pool tests take 10-66 seconds each and slow the test gate 2-8x under load19m2.2M / 38k
  8. #243The <ungated>, <unmet> and <changelog> readers match a tag named in prose10m623k / 12k
  9. #242Tickets that edit protected paths always end held; say so before queueing and requeueing35m2.5M / 24k
  10. #241Report and status treat a hand-merged held branch as one the agent handed back22m3.3M / 30k
  11. #240Idle mark: the skill trigger reads the count before the skill's own labelling27m1.7M / 17k
  12. #239Doctor: the kit's own checkout is never a project, so its project checks are skipped27m660k / 7k
  13. #237pnpmStore mounts the versioned store dir, so sandboxes nest a second store inside the host's9m396k / 7k
  14. #254Size: recommend the pool's limits from measured sandbox and gate peaks19m2.5M / 41k
  15. #253Size: setup and doctor point to sandcastle size while the pool limits are untouched defaults22m1.3M / 14k
  16. #247The run estimate is about half the real cost for a run of carried or conflicting branches29m2.6M / 30k
  17. #246A requeued or resolver-held green branch is re-implemented and re-reviewed in full7m1.3M / 19k
  18. #245Needs you says a stray-held branch changes test files, hiding the real reason10m994k / 9k

bar = minutes in worktokens in / outwent back once, after a red gate or a conflict, and merged on its second try

A test that did not test: "a run below its share does hold back a younger wait" filled the pool. The younger run waited only because no slot was free, so the test also passed with the wait-order check removed.

The review agent on #248, in that run. It rewrote the test so that removing the check fails it. The gates were green either way.

In the 26 runs measured for this example, a ticket ended merged 110 times, in a conflict 8 times and held for a person 6 times. These are historical figures from this TypeScript project, whose tests take a few minutes; a slower suite or a bigger model costs more.

You already run Claude Code all day. It still needs you in the loop.

+ it fitsGitHub Issues or ticket filessmall, closed ticketslint · types · tests · buildyou would rather read a report

- not yettickets that say "make it faster"nothing tests anythingyou want to pair livetickets only in Linear or Jira

Why not a loop of claude -p, subagents or worktrees?

You can, and then you build the rest yourself.

Wired up by handsandcastle-kit
Where the agent runsyour machine, with your credentialsa Docker sandbox per ticket, holding a token that cannot push
Who checks the workthe agent that wrote ita second, stronger agent, against the ticket
Who runs the teststhe agent, when it remembersthe kit, on every branch and again on the merge
Mergingyou, one branch at a timeeach branch as it goes green; a conflict gets a second try
Changes to CI, hooks, install scriptsmerged like the restheld for you
The morning afterscrollback in six terminalsone report: what merged, what is red and why, what needs you

One night, one run

  1. sandcastle runYour gates run on main first. Red there, and nothing is spent.
  2. six sandboxesOne ticket each, on its own branch. A green one lands while the rest work.
  3. a red gate, repaired#41 fails its tests, is repaired, reviewed again and lands. #47 waited for it, and starts.
  4. nine merged#44 and #46 are left for you. Nothing is pushed.
  5. you read the reportPush once you have read it. sandcastle requeue 44 sends a ticket back.

With autonomy: "drain", the run keeps taking turns by itself until the queue is drained, picks up tickets you queue while it runs, and says why it stopped.

How it works

  1. 1/5

    Install

    sandcastle setup
  2. 2/5

    Point at a project

    sandcastle init
  3. 3/5

    Queue tickets

    ready-for-agent
  4. 4/5

    Run, and walk away

    sandcastle run
    1. implement
    2. review
    3. your gates
    4. land

    one sandbox per ticket, in parallel

  5. 5/5

    You push

    sandcastle report

First time? DRY_RUN=1 sandcastle run implements, reviews and gates, and merges nothing.

Each step in full
  1. Install once

    ./bin/sandcastle setup puts sandcastle on your PATH, installs the agent skill for Claude Code, Codex and OpenCode, walks you through your tokens and ends with a health check.

  2. Point it at a project

    sandcastle init reads your stack and fills in the gate commands for you to check against CI. sandcastle build makes the project's image.

  3. Queue tickets

    Label a GitHub issue ready-for-agent, or give a ticket file that status. A Blocked by #12 line, or GitHub's own "blocked by" relationship, holds a ticket until its blocker closes. Ask your agent for /sandcastle queue to tighten the vague ones first, or /sandcastle audit to find work in a repo with no tickets yet.

  4. Run

    sandcastle run, or DRY_RUN=1 sandcastle run the first time: implement, review and gate, but never merge or close. Watch it with sandcastle status, or from Herdr's sidebar.

  5. Land and push

    sandcastle report prints the summary again, and report --run builds one for a run that stopped before printing its own. land merges a branch you fixed, requeue sends a ticket back. Then you push.

Or ask your agent

Before the first run

  • initsets up your gates and a lean sandbox
  • auditfinds work and files it as tickets
  • queueasks one question per vague ticket

Every run after

  • runasks, then starts the run and writes its summary
  • statusreads a live run, or the last one
  • pause / resumeholds a run and carries on without losing work
  • updatepulls the latest kit and says what it changes

/sandcastle Claude Code$sandcastle CodexOpenCode too

What each action does

Before the first run

  • init reads your CI, sets up the gate commands and rules for agents, agrees with you which skills and MCP servers agents see, and checks that every hook runs in the sandbox. It ends with your gates green on main.
  • audit has read-only agents check the repo for bugs, security issues, missing tests and stale docs, and files what they can prove as tickets once you have approved the list.
  • queue walks every open ticket with you. A ticket is queued only when an agent with no chat context could finish it; for the rest you get one question each, with a recommended answer.

Every run after

  • run shows the queue and models, asks before starting, and leaves the run working in the background. When it ends, you get the summary: what merged, what needs you, what to push.
  • status reads a live run, or the last one, and the log behind any red row.
  • pause / resume holds a live run without losing work, then carries on from each ticket's next phase.
  • update pulls the latest kit, rebuilds the project's image and walks you through what the new version changes for it.

Built for long runs

Fails early

Base gates first, then model preflight.

  • your gates, green on main
  • every model answers a one-line preflight
  • your hooks run in the sandbox

agents start

Spends less

A sandbox loads only what you keep.

Shares the machine

Live runs split the sandbox slots.

six sandbox slots, two projects running

Hold a run without losing work: sandcastle pause · resume

The detail

Fails early

  • Your gates on main first. If one fails there, the run stops before any agent starts.
  • Preflight. One short reply from every model, so an exhausted plan or an old CLI stops the run at the start, not halfway through.
  • Hooks proven. The kit checks that your Claude Code hooks run inside the sandbox, and a test can prove a blocking hook still blocks.

Spends less

  • Lean sandboxes. Sandbox agents load only the skills, subagents, commands and MCP servers you keep, five of Claude Code's built-in tools plus any you keep, and never your plugins or Claude Code's own bundled skills: each one costs context on every turn.
  • A failed gate gets one retry. The kit runs a failed gate once more, with no model call, before asking an agent to repair it, so a busy machine does not cost a repair.
  • Picks up where it stopped. A ticket sent back builds on its old branch, and a branch that was already green costs only the gates.
  • Conflicts before review. A branch that conflicts with the base skips review and gates and goes back to resolve. The host also checks for conflicts before landing.
  • One fix for a shared failure. Tickets red on a test another ticket is repairing wait for its fix. A test already red on the base is reported once, instead of repaired on every branch.

Shares the machine

  • Several projects at once. Runs in different projects split the machine's sandbox slots between them rather than starving each other. The pool keeps one slot for a landing while one is near, so a green branch does not wait behind a ticket, and lets a ticket take it otherwise, so no slot sits idle. A ticket waiting only for a gates slot lends its sandbox slot to another ticket's agent pass. sandcastle cap 2 limits a live run's share.
  • CPU and memory counted. Each sandbox has a CPU limit, and a memory limit once the project is measured. Landing, base and verify gates take the run's next free gate slot before ticket gates; sandcastle size recommends pool limits from measured memory, and doctor warns when they exceed the VM.
  • Waits out a busy machine. Gates hold while the machine's CPU pressure is high from other work, for up to 30 minutes a run. A test that timed out under that load gets another gate run, not a repair pass, and the closing summary says when load slowed the gates.
  • A pause keeps the work. Passes in flight finish and green branches still land. Parked sandboxes close, slots go back to other runs and the machine can sleep until you resume.
  • Detached. A run started by your agent outlives the session that started it; sandcastle wait and sandcastle stop find it again.

Know what a run spends and leaves behind

Your plan, on screen

See Claude and Codex subscription windows, percentages and reset times in the status view, read from agents' own events without extra requests. Between runs, sandcastle usage shows a recent saved reading or requests a fresh one.

Set USAGE_PAUSE=90 to pause at 90% of Claude's plan and resume a minute after the window resets; a Codex window at 90% skips the cross-review and the summary lists what landed without one. It is off by default.

Nothing quietly unfinished

A partly-done branch can land, but its ticket stays open with the unmet criterion named. The report tells you what needs a decision and what can run again.

With changelog: true, it also gathers suggested changes and Upgrading notes for you to review. sandcastle report --changelog collects them across runs since the latest tag and lists landed tickets without suggestions separately.

Follow-ups become tickets

Problems agents find outside their ticket are filed for triage. If a later run finds the same problem, it comments on the existing issue. The summary links them, including when a run stops early.

Reviews read the ticket's comments as well as its body - those of the repository's owners, members and collaborators and the ticket's author - so added scope is checked before a ticket closes.

Already using the kit? Ask for /sandcastle update in each project: it shows the changes since that project's last update and any upgrade steps. Then start a new agent session. Release notes and upgrade checks.

Watch it where you already work

sandcastle status works in any terminal, showing run settings, subscription usage with reset times and, when the terminal is wide enough, each ticket's token use, CPU and memory. Two optional extras put the run in front of you.

In Claude Code

A Claude Code session with a band above the prompt: the castle, then sandcastle, my-app, implementing, and counts of tickets working, ready and merged.

An optional mod (a Claude Code plugin, in early access) shows the run above the prompt of the session that started it, names the tickets that need you, and during a long run spends a little allowance refreshing that session's prompt cache, so the turn that closes the run costs less.

The detail

Above the prompt

  • A band while it runs. The run's stage and tokens, and how many tickets are working, need you, are ready to land, are blocked or have merged - and when the session's prompt cache is next refreshed (cache refresh in 55m), so the closing turn is not paid for again.
  • A line when you are needed. A conflict, a red gate, a held branch or a crash pins a line naming the tickets, until they are dealt with or the run ends.

When it ends

  • A closing prompt. When the run's process is gone, the session where you used /sandcastle gets a prompt and writes the closing summary, even if you quit Claude Code and resumed that session in between.
  • Ticket status on demand. /sandcastle-status lists every ticket and where it is, without a model turn.

Between runs

  • Ready tickets. Between runs, a quiet row of sand above the prompt shows the kit's version and how many tickets a run would start now: ♜ sandcastle 0.18.0 · 4 ready - /sandcastle run. It adds update needed when the project has upgrading notes to act on, and names a newer kit release once one is out. The count is read in the background, at most once every ten minutes per project.
  • Hide the reminder. /sandcastle-mark dismiss hides the count until another ticket becomes ready, and a newer release until the next one; hide turns the mark off for the project.

In Herdr

♜ 4/9 · 1 needs you

Herdr is a terminal multiplexer for coding agents, and the kit works with the Herdr app and anything else on herdr-core, and with Herdr TUI. In either, the run shows in the sidebar and says when it needs you.

The detail

Over any tab (Herdr TUI)

  • The status view on a key. Herdr's prefix key, then Shift+S, opens it over whatever you are doing; q puts you back. Prefix, then Shift+E, shows the last run's report.
  • A ticket a click away. Use the status view's click hint (Cmd-click in iTerm2, Ctrl-click in Terminal.app and Ghostty) to open a ticket's card: its state, each pass with its outcome and time, and why it is held or red, with a key for each pass's log.

In the sidebar (Herdr TUI)

  • The run at a glance. The run is one entry in the sidebar, and its workspace reads ♜ 4/9 · 1 needs you, red when something needs you. The tab bar lists every live run on the machine, and the sidebar shows Claude and Codex plan usage when available.
  • Each sandbox, if you want them. With sandbox panes on (herdr: { panes: "all" } in the project config, or SANDBOX_PANES=all for one run), each one is named after its ticket with its step and time in it: review · 12m.

Out of your way (Herdr TUI)

  • One status view, run after run. A run started by your agent runs detached and outlives the session that started it. Its status view opens in a tab of its own; if the pane is still there in the same terminal and workspace, the next run reuses it where you left it. The view returns after a Herdr restart and shows the closing report when the run ends.
  • Set up when you say. sandcastle herdr configure --tui shows what it adds to Herdr TUI's config and asks first; --remove --tui takes it out again.

In the Herdr app (herdr-core)

  • Beside you, in the app's own look. With the kit's mod installed (sandcastle herdr configure --app), a run started in the app opens a native status view in a pane beside you: the same castle, lanes, table, counts and notes. A row opens the ticket's card or peeks at its sandbox, and a line across the top carries Pause, Resume and the closing report. Where the mod is missing or fails, and in any other herdr-core client, the run opens the terminal status view as a terminal split into that tab; sandcastle status opens it by hand. The next run finds the view by name and opens a fresh one in its place.
  • Run state. The sidebar shows working, blocked, done or error, and the merged share of the run. Blocked raises the app's needs-you alert.
  • Every sandbox, under the run. Each running sandbox is a terminal listed under the run's agent in the sidebar, named after its ticket (shop-12), with no pane in your tab; click it to peek at its log. With herdr: { panes: "all" } each one also gets a pane in your tab. It closes itself once its run is gone, even a run killed outright.
  • Not there yet. The key over any tab and the tab bar line come from the Herdr TUI plugin, and have no herdr-core counterpart yet.

Safe to leave alone

Agents run with permission prompts off, inside Docker. The container is the boundary, and only a green, reviewed branch gets through the wall.

Docker sandbox

An agent, prompts off

  • a token that cannot push
  • a ticket, which grants no permissions
  1. Reviewa second agent, against the ticket
  2. Your gateslint, tests and build, run by the kit itself
  3. Risky? It waits for youCI, hooks, install scripts, protected paths

Your machine

Merged into your local branch

  • .git is fingerprinted
  • host hooks stay off

GitHub

Nothing pushed

  • labels, comments, completed issues closed
  • follow-up issues filed for triage
The detail

Into the sandbox

  • A token that cannot push. Only a fine-grained GitHub token for issues goes in, and sandcastle doctor --verify checks it cannot push. An empty value is refused, so a host API key cannot leak in.
  • Sandbox agents cannot add worktrees. Claude Code's worktree tools are denied in sandboxes, and the git guard refuses git worktree add in the shared .git.
  • Tickets grant no permissions. A ticket that asks an agent to touch .git/, credentials or a push is not the work, and the guards below hold if an agent tries anyway.

Before a merge

  • Review, then your gates. A second agent reviews every branch against its ticket and fixes what it finds. Then the orchestrator, never the agent, runs your lint, tests and build. Only a green branch merges, and the merged branch is gated again.
  • Risky changes wait. A green branch that changes hooks, CI, agent settings, package-manager config, install scripts or a path you protect is labelled ready-for-human and left for you. So is one that adds a file over 50 MB, a repair whose review failed, and a conflict resolution that drops lines git had merged.

On your machine

  • Nothing is pushed. Green branches merge into your local base branch. The kit never pushes or deploys; on GitHub it labels and comments on issues, closes completed ones and files agents' follow-ups for triage.
  • .git is fingerprinted. If a sandbox changes .git/config, HEAD, info/ or hooks, or moves your base branch, the run stops before your machine runs another git command there. The stop names each changed .git/config key. At the next start, the kit compares the git settings that can run programs, the hooks and .git/modules with the state the last run left.
  • Host hooks stay off. During a run the kit's own git calls on your machine ignore hooks, so a branch that adds one cannot run it as it lands.

Install

  1. Install the kit, once per machine:

    $ git clone https://github.com/henkisdabro/sandcastle-kit.git ~/sandcastle-kit && cd ~/sandcastle-kit && pnpm install && ./bin/sandcastle setup
  2. Point it at a project:

    $ cd ~/code/your-project && sandcastle init && sandcastle build
  3. Mark a couple of tickets ready-for-agent and try a dry run. It implements, reviews and gates them, but never merges or closes a ticket:

    $ DRY_RUN=1 sandcastle run

Needs macOS or Linux, Node 22.18+, pnpm, git 2.31+, ps (procps, on Linux) and the GitHub CLI signed in (skippable with ticket files). On Linux, use rootful Docker Engine as a normal user in the docker group; rootless Docker, userns-remapped Docker and Podman are refused. On macOS, use OrbStack or Docker Desktop. Full requirements.

Questions

What does it cost to run?

The kit is free and MIT-licensed. Agents use your Claude subscription or an Anthropic API key through Claude Code; an API key takes precedence and the kit asks before spending it. Codex cross-review uses your ChatGPT plan or OpenAI API key. Runs using the same account share its allowance. The status view shows subscription usage and reset times from agent events, without extra requests. Between runs, sandcastle usage shows a recent saved reading or requests a fresh one. USAGE_CHECK=1 checks Claude plan usage before starting tickets; USAGE_PAUSE=90 opts into pausing at 90% of a Claude plan window and resuming a minute after its reset; a Codex window at 90% skips the cross-review instead. Without usage pause, an agent hitting the limit stops the queue.

Which models does it use?

By default Claude Sonnet 5.5 implements and Claude Opus 5.5 reviews. A model: or effort: label sets the implementer's model or effort for one ticket, and CROSS_REVIEW=1 adds a third review by an OpenAI model through Codex.

Does it push to GitHub?

No. Green branches merge into your local base branch. A completed ticket is closed with a comment; a partly-done ticket stays open with the unmet criterion named. Agents' follow-ups are filed for triage. You push when you are happy with what landed.

What about my own work in that repository?

A run refuses to start on a dirty tree or off the base branch, and it merges into that checkout while it runs. A commit, pull or merge on the base branch mid-run stops the run, and the start line says so. Leave the checkout alone until the run ends, and do your own work in another clone or worktree. You can set an upstream for your own branch in another worktree, including with git push -u or gh pr create. Other changes to the shared git config stop the run, and the stop names the changed keys. If the previous run ended cleanly, the next run accepts a remote or a hook manager's hooks you added in between.

What if a branch is green but wrong?

Then it is in your local branch and nowhere else. A second agent reads every branch against its ticket before your gates run, and the report lists what merged, so you read before you push. Behaviour that no test covers has only that review between it and your branch.

What happens on a merge conflict?

If a branch conflicts with the base, it gets one more try in the same run. A conflict found during ticket work skips review and gates; one found at landing is caught on the host, before a sandbox starts. A second conflict is left for you, and so is a resolution that edits a file git had merged cleanly without naming the file and its reason.

Can the text of a ticket make an agent do something else?

It can try. The sandbox holds a token that only reaches issues, the kit runs your gates itself, and a branch that changes CI, hooks, install scripts or a path you protect waits for you whatever the ticket said.

Can a run go all night?

Yes. A run keeps the machine awake while work is in flight (caffeinate on macOS, systemd-inhibit on Linux). Closing a MacBook's lid still sleeps it unless it is on power with an external display. Under WSL, Windows decides when the PC sleeps, so keep it awake in Windows' power settings. A paused run lets the machine sleep once its passes finish. A ticket whose blocker lands starts in the same run, and autonomy: "drain" keeps taking turns until the queue is drained or something stops it; end-of-run gates that went red only from machine load do not, as the next turn re-gates the base first. At autonomy 2, 3 and "drain", a ticket you queue while the run is live is taken as a follow-on turn, not left for the next run. Partly-done tickets are retried unless the remainder needs a person's decision; a drain stops after the same ticket is left partly done twice.

Do I need Matt Pocock's skills?

No, but they help. His /to-tickets and /triage are a good way to write tickets an unattended agent can finish, and the kit reads the tracker and labels his setup skill records.

Does it work with the new Herdr app?

Yes. In the Herdr app with the kit's mod installed (sandcastle herdr configure --app), a run opens a native status view in the app's own look: the same castle, lanes, table, counts and notes, and reports its state to the sidebar, with each running sandbox listed under the run's agent there. It falls back to the terminal status view where the mod is missing or fails, and on anything else on herdr-core. The terminal status view stays the portable view everywhere else, and sandcastle status opens it by hand. Herdr TUI works as before. Its plugin's key over any tab and tab bar line have no herdr-core counterpart yet. sandcastle doctor names the host it found.

Linear, Jira, Windows?

Linear issues can block a ticket today, but the queues are GitHub Issues and Markdown ticket files. The kit runs on macOS and Linux.

Built on Sandcastle

Sandcastle by Matt Pocock does the sandboxing, worktrees and agent orchestration underneath. This kit is one opinionated way to put it to work. If it helps you, go and star the original.