| name | setup-sandcastle |
| description | Configure Sandcastle for agent delegation -- headless run(), HITL interactive(), parallel sandboxes, branches. Use when delegating to autonomous agents, parallelizing implementation, or running interactive reviews. |
Setup Sandcastle
Sandcastle orchestrate agents in sandboxes with branch strategies. Two modes:
run() -- headless (--print), stream-JSON parsed. CI, batch, overnight.interactive() -- full TUI passthrough (stdin/stdout/stderr). Human watch + intervene. HITL review, pair-review, local dev.
Both modes: hooks fire inside each session. Dev lifecycle enforced regardless of launch method.
Capabilities: task picking (GitHub issues -> one agent per issue), parallel N agents in isolated sandboxes, HITL review with full TUI, noSandbox() for git worktrees only, hooks in each session, branch strategies (head, merge-to-head, branch).
sequenceDiagram
participant GH as GitHub Issues
participant Main as main.ts
participant A1 as Agent 1 (run)
participant An as Agent N (run)
participant Rev as Reviewer (interactive)
GH->>Main: Fetch labeled issues
par Headless parallel execution
Main->>A1: Issue #1 (Docker sandbox)
A1->>A1: development-lifecycle (6 phases)
and
Main->>An: Issue #N (Docker sandbox)
An->>An: development-lifecycle (6 phases)
end
A1->>Rev: Branch for HITL review
Note over Rev: Human watches TUI, can intervene
Rev->>Main: Approved -- merge to head
Steps
1. Install
bun add -D @ai-hero/sandcastle && bunx sandcastle init
2. Configure .sandcastle/.env
ANTHROPIC_API_KEY=sk-ant-...
3. Choose launch mode
| Scenario | Mode | Sandbox |
|---|
| CI/batch/overnight | run() | docker() |
| Parallel 5+ issues | run() | docker() |
| Local dev quick review | interactive() | noSandbox() |
| Pair-review with human | interactive() | docker() or noSandbox() |
| Single interactive session | interactive() | noSandbox() |
4. Orchestration Script
See REFERENCE.md for templates: headless batch, HITL review, mixed pipelines.
5. Run
bunx tsx .sandcastle/main.ts
Each agent: read issue -> development-lifecycle -> hooks enforce patterns -> commit -> review -> merge.
See REFERENCE.md for templates + prompt patterns.
