sandcastle-kit / site

# sandcastle-kit

> An opinionated issue-burndown kit built on Sandcastle by Matt Pocock. It runs Claude Code agents unattended in Docker sandboxes, one per ticket: an implement agent, a stronger review agent, the project's own gates run by the orchestrator, green branches merged locally, nothing pushed. Tickets are GitHub Issues or Markdown files in the repo. Each ticket lands as it goes green, a conflict gets one more try in the same run (one found before review skips review and gates), and a ticket whose blocker lands starts at once; a blocker can be named in a Blocked by line or a GitHub issue dependency. A red gate is re-run once, with no model, before any repair pass. Sandboxes are lean: the project's skills and MCP servers are hidden from agents unless kept, plugins and Claude Code's bundled skills are always hidden, and a pass gets five of Claude Code's built-in tools plus any kept in lean.keep. An agent skill (/sandcastle in Claude Code, $sandcastle in Codex, read by OpenCode) sets a project up, audits a repo for work and files it as tickets, triages tickets into the queue, starts and closes runs, and updates the kit. A partly-done branch keeps its ticket open with the unmet criterion named; higher autonomy levels retry its remainder unless it needs a person's decision, and at levels 2, 3 and drain a run takes tickets queued while it was live as a follow-on turn. Agents' follow-ups are filed as tickets for triage; repeat findings become comments on the existing issue. A clone can keep its own run settings in a gitignored .sandcastle/config.local.json. Pause and resume hold a live run without losing work, releasing slots once passes finish. The status view shows Claude and Codex subscription usage from agent events; opt-in USAGE_PAUSE pauses at a threshold and resumes after reset. sandcastle usage prints plan usage between runs. Anthropic API-key spend is announced and requires confirmation. Sandboxes have CPU limits, gates hold while the machine's CPU pressure is high from other work (LOAD_PAUSE, on by default, at most 30 minutes a run) and a test timeout under that load is re-gated rather than repaired, landing gates get priority within a run, the pool keeps one sandbox slot for any run's landing while one is near, a ticket waiting only for a gates slot lends its sandbox slot to another ticket's agent pass, and sandcastle size recommends pool limits from measured memory. First-class support for Herdr (https://herdr.dev): a plugin that opens the status view over any tab, and the run's progress in Herdr's sidebar. An optional Claude Code mod shows a run above the prompt of the session where /sandcastle was used, tells that session when the run ends, refreshes its prompt cache during a long run for a little allowance, and between runs shows how many tickets are ready in a row above the prompt. macOS and Linux, Node 22.18+ (rootful Docker Engine as a normal user; rootless, userns-remapped Docker and Podman are refused on Linux). MIT licence.

An AI coding agent setting this up for someone should start at the README's section written for agents, then run `sandcastle doctor`.

## Docs

- [README](https://github.com/henkisdabro/sandcastle-kit/blob/main/README.md): who it is for, quick start, how a run works, and a table of the docs below
- [Setting up a project](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/setup.md): `sandcastle init`, gates, the Dockerfile, lean sandboxes and hooks
- [Tickets and the queue](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/queue.md): a ticket an agent can finish, the queue label, blockers, trackers
- [Running](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/running.md): starting, detached runs, pausing, the closing summary, re-runs
- [Commands](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/commands.md) and [Configuration](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/configuration.md): every command, key, setting and variable
- [Safety model](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/safety.md), [Concurrency](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/concurrency.md), [Troubleshooting](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/troubleshooting.md)
- [Herdr](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/herdr.md) and [the Claude Code mod](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/claude-mod.md): watching a run
- [For AI coding agents](https://github.com/henkisdabro/sandcastle-kit/blob/main/README.md#-if-you-are-an-ai-coding-agent-reading-this): the steps an agent follows to install and use the kit
- [Install](https://github.com/henkisdabro/sandcastle-kit/blob/main/docs/INSTALL.md): requirements, what `sandcastle setup` does, a manual install, updating
- [Changelog](https://github.com/henkisdabro/sandcastle-kit/blob/main/CHANGELOG.md): releases, with Upgrading notes per version

## Source

- [Repository](https://github.com/henkisdabro/sandcastle-kit)
- [Sandcastle](https://github.com/mattpocock/sandcastle): the library underneath