Contribute to claude-sandbox#

A task recipe for contributors. For the design rationale behind the bash-only constraint and the sandbox itself, see the explanations.

File an issue or open a discussion#

Issues and pull requests are handled through GitHub. Check for an existing issue before filing a new one.

  • Bug report or concrete change → file an issue. If the change is large, file the issue before opening a pull request so the scope can be agreed first.

  • Open-ended question or idea → if it isn’t obvious when it could be “closed”, raise it as a discussion instead.

Respect the bash-only ethos#

The tool is bash all the way down. There is no Python package, no uv, and no pytest in the tool itself — do not add them back. The one isolated Python dependency in the repo is the docs toolchain (see Build the docs locally); it does not make the tool a Python project.

Run the tests CI runs#

Clone the repo and run the same three commands CI runs:

git clone https://github.com/gilesknap/claude-sandbox.git
cd claude-sandbox
bash tests/bwrap_argv.sh
bash tests/smoke.sh
bash tests/promote.sh

No uv sync, no pytest, no twine. Development is best done inside a vscode devcontainer; the repository ships configuration for a containerised development environment.

Edit shipped skills, commands, and hooks#

The repo’s own .claude/ is the canonical source of the skills, commands, and hooks the installer ships. Editing one entry updates both how Claude behaves on this repo and what just promote lands in target workspaces — so make those edits in .claude/, not in a copied target.

Build the docs locally#

The docs toolchain is the project’s one isolated Python dependency, pinned in docs/requirements.txt. The quickest way to preview is the docs recipe, which provisions an isolated .venv-docs on first run and serves the site with live reload:

just docs          # http://localhost:8000, rebuilds on save
just docs 9000     # choose a different port

Or build it once by hand into a throwaway virtualenv:

python -m venv venv
. venv/bin/activate
pip install -r docs/requirements.txt
sphinx-build -b html docs build/html

Open build/html/index.html to preview. CI builds with -W (warnings are errors), so resolve any warning the local build prints.