8. Bash-only: no Python package, uv, or pytest#

Date: 2026-05-12

Status#

Accepted

Context#

The tool’s implementation drifted: embedded bash → standalone bash → Python package + typer CLI → bash-only (commits 25e67ce, a35b8ee, then bf65407; issue #14 / PR #15). The Python era was roughly 110 KB — pyproject.toml, a uv lockfile, a pytest suite, a typer CLI. But the tool is fundamentally one bash function building a bwrap argv, and spreading the security-critical bits across several Python modules made them harder to audit, not easier.

Decision#

Bash-only. The security surface is two short bash files — the shadow and the installer — that you can read top to bottom. No pyproject.toml, uv.lock, src/claude_sandbox/, or test_*.py. The one allowed Python is the fully isolated docs/ toolchain (Sphinx), which touches nothing security-critical.

Consequences#

  • The security surface is a couple of files you can read top-to-bottom — the same auditability principle that motivated 3. Live in a standalone repo, extracted from python-copier-template.

  • Tests are bash: tests/bwrap_argv.sh (pure argv-builder assertions), tests/smoke.sh, tests/promote.sh.

  • Root CLAUDE.md states the rule (“Bash-only. No Python package, no uv, no pytest — don’t add them back”); the claude-sandbox skill (Reversal 1) lists the regressions to refuse (“a small Python CLI for nicer errors,” “bring back pytest — it’s only a little code”).

  • The v2 “ship as a PyPI package / uvx one-liner” idea (issue #26) reopens this and must re-justify against auditability before proceeding.