claudebox/.planning/ROADMAP.md

Roadmap: claudebox

Overview

claudebox is a Nix-packaged bwrap sandbox wrapper for Claude Code. The roadmap moves from a working sandbox (Phase 1) through CLI polish (Phase 2) to sandbox-aware prompting (Phase 3). Phase 1 is the bulk of the work -- once Claude runs inside bwrap with env isolation, filesystem isolation, and tool provisioning, the remaining phases add UX and developer experience improvements.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Minimal Viable Sandbox - Working claudebox command that launches Claude in bwrap with full isolation and tool provisioning
• Phase 2: Env Audit and CLI Polish - Pre-launch env review, --yes, --dry-run, and --check flags
• Phase 3: Sandbox-Aware Prompting - Injected CLAUDE.md so Claude knows its capabilities and constraints

Phase Details

Phase 1: Minimal Viable Sandbox

Goal: User can run claudebox in any project directory and get a fully functional Claude Code session with secrets invisible Depends on: Nothing (first phase) Requirements: SAND-01, SAND-02, SAND-03, SAND-04, SAND-05, SAND-06, SAND-07, SAND-08, SAND-09, SAND-10, SAND-11, SAND-12, SAND-13, SAND-14, SAND-15, TOOL-01, TOOL-02, TOOL-03, GIT-01, GIT-02, NIX-01, NIX-02, NIX-03, UX-06 Success Criteria (what must be TRUE):

1. Running nix run or nix profile install produces a working claudebox command
2. claudebox launches Claude Code inside bwrap; env inside the sandbox shows only allowlisted variables (no SSH_AUTH_SOCK, AWS_PROFILE, etc.)
3. Secret paths (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, age keys, /var/lib/tailscale) are not visible inside the sandbox
4. Claude can run curl https://example.com, git status, , jq --help (comma), and nix shell nixpkgs#python3 -c python3 --version inside the sandbox
5. Ctrl+C terminates the session cleanly; exit code from Claude passes through to the caller Plans: 2 plans

Plans:

• 01-01-PLAN.md -- Create flake.nix and claudebox.sh with complete bwrap sandbox
• 01-02-PLAN.md -- Build verification and manual sandbox smoke test

Phase 2: Env Audit and CLI Polish

Goal: User can review exactly what enters the sandbox before launch, and has diagnostic tools for troubleshooting Depends on: Phase 1 Requirements: UX-01, UX-02, UX-03, UX-04, UX-05 Success Criteria (what must be TRUE):

1. Running claudebox without --yes prints all env vars being passed into the sandbox and prompts for confirmation before proceeding
2. Running claudebox --yes or claudebox -y skips the env audit and launches immediately
3. Running claudebox --dry-run prints the full bwrap command without executing it
4. Running claudebox --check reports whether bwrap exists, required Nix packages are available, and ~/.claudebox exists Plans: 2 plans

Plans:

• 02-01-PLAN.md -- Refactor flag parsing, add --check and --dry-run modes
• 02-02-PLAN.md -- Env audit display with grouping, masking, and confirmation prompt

Phase 3: Sandbox-Aware Prompting

Goal: Claude inside the sandbox knows it is sandboxed, how to install tools, and what is unavailable Depends on: Phase 1 Requirements: AWARE-01, AWARE-02 Success Criteria (what must be TRUE):

1. First run of claudebox creates a default CLAUDE.md in ~/.claudebox/ if none exists
2. The injected CLAUDE.md tells Claude it is in a bwrap sandbox, how to use comma (, <tool>) and nix shell for tool installation, and that SSH/GPG/cloud credentials are unavailable Plans: 1 plan

Plans:

• 03-01-PLAN.md -- Add SANDBOX.md generation and CLAUDE.md import management

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3

Phase	Plans Complete	Status	Completed
1. Minimal Viable Sandbox	2/2	Complete	-
2. Env Audit and CLI Polish	0/2	Planned	-
3. Sandbox-Aware Prompting	0/1	Not started	-