Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/sandbox.md
Open on GitHub

What 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-specs recipe named drift-check
  • Use /sandbox to 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.md

Call it with /sandbox. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Testing and QA →

From the same set83

The whole set →
bench-sync bench-sync — a command for Claude Code and Codex that bakes benchmark cells and measures the current spec-kit and Companion extension versions. Use it to track how performance changes as tools are updated. CX Codex +1 ★ 110repo stars speckit.companion.living-show speckit.companion.living-show is a Claude Code command that prints requirement headings, one complete requirement, or rules tied to a file. Run it to inspect a specific part of a living spec without opening the whole document. CX Codex +1 ★ 110repo stars speckit.companion.status speckit.companion.status — a command for Claude Code and Codex reads .spec-context.json and reports the active spec’s step, status, decisions, and next action. It is read-only. CX Codex +1 ★ 110repo stars speckit.plan speckit.plan runs an implementation planning workflow from a feature spec, generating research.md, data models, and API contracts. CX Codex GP ChatGPT ★ 110repo stars release-qa release-qa is a Claude Code command that checks code before release. It compares the last version tag, runs automated and manual checks, and blocks /publish until all checks pass. CX Codex +1 ★ 110repo stars install-local The install-local command for Claude Code builds and installs local speckit-companion VS Code and spec-kit extensions, bumping the patch version to trigger an editor reload banner. CX Codex +1 ★ 110repo stars speckit.companion.living-drift speckit.companion.living-drift finds capability files that changed after their living spec was last committed. Use it to spot project changes that have not made it back into the spec. CX Codex +1 ★ 110repo stars speckit.companion.resume speckit.companion.resume is a command for Claude Code that resumes spec-driven development after a pause. It carries recorded decisions forward and starts the next pipeline step. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open