sandbox — Claude Code command: what it does, how to install
This command builds throwaway SpecKit sandboxes from recipes or lists available recipes and existing folders. It works with Claude Code and Codex.
MIT ★ 110 updated 2026-10-19
.claude/commands/sandbox.mdWhat sandbox does
sandbox creates a small temporary SpecKit project from a recipe stored in the sibling speckit-sandboxes repository. With no arguments, it lists recipes and existing sandboxes; where prints the sandbox root. A taken name is never overwritten, so a new folder receives a suffix such as -2 or -3.
The --dev form installs Companion from the current checkout by setting COMPANION_DIR="$PWD". Arguments after the name are passed to the recipe unchanged, which supports scenarios such as living-specs. The command does not delete folders or write into this repository.
The speckit-sandboxes checkout must exist before use because .claude/sandboxes-env.sh sets the repository and sandbox-root paths. Without that checkout, the command stops. A failed build leaves its partly created folder in place.
What it helps with
- create a temporary SpecKit project from a recipe
- list the recipes available to the command
- inspect sandboxes that already exist
- print the sandbox root path
- build a sandbox with Companion from the current checkout
Example prompts for the agent
- Build a sandbox from the
living-specsrecipe nameddrift-check - Use
/sandboxto list the recipes and existing sandboxes - Print the sandbox root with
/sandbox where
How to install sandbox
Manually: put the files in place
.claude/commands/sandbox.mdCall it with /sandbox. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/sandbox.mdCall it with /prompts:sandbox. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/sandbox.prompt.mdManually: put the files in place
.gemini/commands/sandbox.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about sandbox
How do I install sandbox in Claude Code?
Copy the command file to .claude/commands/sandbox.md.
What does the sandbox command do?
It builds a temporary SpecKit sandbox from a recipe, or lists recipes and existing sandboxes. The where form prints the sandbox root.
What happens when I use sandbox with --dev?
Companion is taken from the current checkout through COMPANION_DIR="$PWD". The vscode-qa-stock, copilot-stock, and claude-mod-stock recipes reject --dev, so no build is made.
Source text
sandbox.md · MIT
---
allowed-tools: Bash(. .claude/sandboxes-env.sh:*), Bash("$SANDBOXES_REPO"/new-sandbox.sh:*), Bash(ls:*)
description: Build a throwaway SpecKit test sandbox from a recipe, or list the recipes and the sandboxes that exist
argument-hint: "[<recipe> [name] [--dev] | where]"
---
## Your task
Build one test sandbox, or show what there is. A sandbox is a small throwaway project in a known starting state; the recipes live in the sibling `speckit-sandboxes` repo and every built sandbox lands under its sandbox root, never in this repo.
Shell state does not persist between Bash calls, so start each one with `. .claude/sandboxes-env.sh`. It sets `$SANDBOXES_REPO` (the sibling checkout) and `$SANDBOXES_DIR` (the sandbox root). If it says there is no checkout, relay that line and stop.
### Read `$ARGUMENTS`
- **empty**: list. Print the recipes, then the sandboxes that already exist:
```bash
. .claude/sandboxes-env.sh && "$SANDBOXES_REPO"/new-sandbox.sh --list
. .claude/sandboxes-env.sh && ls -1 "$SANDBOXES_DIR" 2>/dev/null || echo "(no sandboxes yet)"
```
Show both as two short lists, with the root's path above the second. Do not build anything. Two folders in the second list are not sandboxes, so say what they are when they show up: `bench-cells` holds the benchmark's cells and `awesome-copilot` is `/publish-canvas`'s upstream clone.
- **`where`**: print the sandbox root and nothing else.
```bash
. .claude/sandboxes-env.sh && "$SANDBOXES_REPO"/new-sandbox.sh --where
```
- **`<recipe> [name]`**: build one. The name defaults to the recipe, and a name that is taken is never reused: the new sandbox becomes `<name>-2`, then `-3`.
```bash
. .claude/sandboxes-env.sh && "$SANDBOXES_REPO"/new-sandbox.sh <recipe> [name]
```
- **`<recipe> [name] --dev`**: the same, with Companion installed from this checkout in place of the published build. `COMPANION_DIR` points the recipe here; without it the recipe uses the `speckit-companion` folder beside the sandboxes repo, which is not this checkout when you are in a worktree.
```bash
. .claude/sandboxes-env.sh && COMPANION_DIR="$PWD" "$SANDBOXES_REPO"/new-sandbox.sh <recipe> [name] -- --dev
```
A recipe with no Companion (`vscode-qa-stock`, `copilot-stock`, `claude-mod-stock`) refuses `--dev`; say so and build nothing.
Anything else after the name goes to the recipe after `--`, unchanged: `living-specs` takes its scenario that way (`/sandbox living-specs drift-check ls-6`). An unknown recipe prints the list; relay it.
### Report
The recipe ends by printing `Sandbox ready: <folder>` and what to do in it. Relay exactly that: the folder, and what to type next. Add nothing of your own, and do not open the folder or run anything in it.
### Guardrails
- This command never deletes anything: not a sandbox, not a file inside one, not the root. Throwing a sandbox away is the user's call and the user's `rm`.
- It never builds over an existing folder, and never writes into this repo.
- A build that fails leaves its half-built folder in place. Name it in the report so the user can look, and do not clean it up.
© alfredoperez · MIT · alfredoperez/speckit-companion