toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/milestones/v1.0-ROADMAP.md
Christopher Mühl ee70f08909 fix(planning): restore v2.0 state after executor regression in 6465da8 
Commit 6465da8 (phase 04-01 executor) was made from a stale worktree
predating v1.0 completion (ee686a3), accidentally reverting:
  - ROADMAP.md from v2.0 (phases 4-7) back to pre-v1.0 structure
  - STATE.md from milestone v2.0/active back to v1.0/executing
  - Deleted .planning/milestones/ (v1.0 archive files)

This commit restores the correct state:
  - ROADMAP.md: v2.0 structure with v1.0 archived + phase 04 marked complete
  - STATE.md: milestone v2.0, phase 04 complete (1/4 phases, 25%)
  - milestones/: v1.0-ROADMAP.md + v1.0-REQUIREMENTS.md restored
  - MILESTONES.md + RETROSPECTIVE.md: restored from v1.0 completion
  - phases/01-03/: staged deletions of v1.0 phase artifacts (cleaned up)
  - v1.0-MILESTONE-AUDIT.md: audit report documenting the corruption

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-10 12:44:41 +00:00

4.1 KiB
Raw Blame History

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 -