sandcastlelisted
Install: claude install-skill av/skills
# Sandcastle
Sandcastle (`@ai-hero/sandcastle`) orchestrates AI coding agents inside isolated sandbox environments. It manages git worktrees, boots containers, runs agents with structured prompts, collects commits, and merges results back to branches — all from a single `run()` call.
## Installation
```bash
npm i @ai-hero/sandcastle
npx sandcastle init # scaffolds .sandcastle/ with Dockerfile and prompt templates
npx sandcastle docker build-image # builds the Docker image from .sandcastle/Dockerfile
```
## Quick Start
```typescript
import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
const result = await run({
agent: claudeCode(),
sandbox: docker(),
promptFile: "./.sandcastle/prompt.md",
});
console.log(result.commits); // [{ sha: "abc123" }, ...]
console.log(result.branch); // branch the agent worked on
```
## Core Concepts
### The Four Entry Points
| Function | Use Case |
|---|---|
| `run(options)` | One-shot agent invocation. Full lifecycle managed automatically. |
| `createSandbox({ branch, sandbox })` | Reusable sandbox on an explicit branch. Call `.run()` multiple times. |
| `createWorktree({ branchStrategy })` | Independent git worktree. Call `.run()`, `.interactive()`, or `.createSandbox()`. |
| `interactive(options)` | Interactive terminal session with an agent. Human-in-the-loop. |
### Agent Providers
```typescript
import { claudeCode, codex, opencode, pi } from "@ai-h