Run AI coding agents inside isolated sandboxes with git worktrees.
@alembic/factory orchestrates AI coding agents (Claude Code, Codex, Cursor, OpenCode, Copilot, Pi) inside Docker, Podman, or no-sandbox environments. Each run creates a git worktree, runs the agent against a prompt file, captures commits, and optionally merges the result back.
It supports interactive sessions, multi-iteration loops, structured output, session resume/fork, and branch strategies (head, merge-to-head, or explicit branch).
Think of it like… a clean room for software surgery: the patient (your repo) is isolated, the surgeon (agent) operates, and the incision is either merged or discarded.
The public API is small: run, createSandbox, createWorktree, interactive, agent providers, sandbox providers, and Output. Internally it uses Effect for functional composition, but consumers see Promise-returning functions. The package is vendored and adapted from @ai-hero/sandcastle.
# scaffold a factory config pnpm exec alembic-factory init --agent claude-code --sandbox docker # build the sandbox image pnpm exec alembic-factory docker build-image --image-name myproject:sandcastle
The scaffold creates a .sandcastle/ directory with a prompt and a main.ts that imports @alembic/factory. The agent loop enforces idle and completion timeouts, captures JSONL sessions for resume/fork, and supports prompt argument substitution with {{KEY}} tokens.
Run pnpm exec alembic-factory init and inspect the generated .sandcastle/main.ts. Identify the agent and sandbox providers.