@kokorolx/ai-sandbox-wrapper 2.7.0 → 3.0.0

package/bin/ai-run

@@ -4,9 +4,10 @@ set -e
 # Show help if requested
 show_help() {
   cat << 'EOF'
-Usage: ai-run <tool> [options] [-- tool-args...]
+Usage: ai-run [tool] [options] [-- tool-args...]
 
 Run AI tools in a secure Docker sandbox.
+When no tool is specified, opens an interactive shell with all installed tools.
 
 Options:
   -s, --shell              Start interactive shell instead of running tool directly
@@ -35,12 +36,13 @@ OpenCode Server Authentication (web/serve mode only):
   Precedence: --password > --password-env > OPENCODE_SERVER_PASSWORD env > interactive prompt
 
 Examples:
+  ai-run                                  # Open interactive shell with all tools
   ai-run claude                           # Run Claude in sandbox
   ai-run opencode web -e 4096             # Run OpenCode web with port exposed
   ai-run opencode web -p secret           # Run with password
   ai-run opencode --shell                 # Start shell, run tool manually
   ai-run aider -n mynetwork               # Connect to Docker network
-  ai-run opencode --git-fetch              # Git fetch only (no push)
+  ai-run opencode --git-fetch             # Git fetch only (no push)
 
 Documentation: https://github.com/kokorolx/ai-sandbox-wrapper
 EOF
@@ -126,11 +128,26 @@ if [[ "${1:-}" == "--help-env" ]]; then
   show_help_env
 fi
 
-TOOL="$1"
-shift 2>/dev/null || { echo "❌ ERROR: No tool specified. Use 'ai-run --help' for usage."; exit 1; }
+TOOL="${1:-}"
+if [[ -n "$TOOL" && ! "$TOOL" =~ ^- ]]; then
+  shift
+else
+  TOOL=""
+fi
+
+# Handle no tool specified
+if [[ -z "$TOOL" ]]; then
+  if [[ ! -t 0 ]] || [[ ! -t 1 ]]; then
+    echo "❌ ERROR: No tool specified and no TTY available."
+    echo "   Use: ai-run <tool> [args...]"
+    exit 1
+  fi
+  SHELL_MODE=true
+fi
 
 # Parse flags
-SHELL_MODE=false
+# Note: SHELL_MODE may already be true if no tool was specified
+SHELL_MODE="${SHELL_MODE:-false}"
 NETWORK_FLAG=false
 NETWORK_ARG=""
 EXPOSE_ARG=""
@@ -462,7 +479,7 @@ while IFS= read -r ws; do
 done < <(read_workspaces)
 
 if [[ "$ALLOWED" != "true" ]]; then
-  echo "⚠️  SECURITY WARNING: You are running $TOOL outside a whitelisted workspace."
+  echo "⚠️  SECURITY WARNING: You are running ${TOOL:-shell} outside a whitelisted workspace."
   echo "   Current path: $CURRENT_DIR"
   echo ""
   echo "Allowing this path gives the AI container access to this folder."
@@ -540,17 +557,86 @@ if [[ "$(uname)" == "Darwin" ]] && [[ -t 0 ]]; then
 fi
 
 if [[ "$AI_IMAGE_SOURCE" == "registry" ]]; then
-  IMAGE="registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-${TOOL}:latest"
+  IMAGE="registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-sandbox:latest"
 else
-  IMAGE="ai-${TOOL}:latest"
+  IMAGE="ai-sandbox:latest"
+fi
+
+# Tool validation (warn if tool not in config.json)
+if [[ -n "$TOOL" ]]; then
+  if command -v jq &>/dev/null && [[ -f "$AI_SANDBOX_CONFIG" ]]; then
+    INSTALLED_TOOLS=$(jq -r '.tools.installed // [] | .[]' "$AI_SANDBOX_CONFIG" 2>/dev/null)
+    if [[ -n "$INSTALLED_TOOLS" ]] && ! echo "$INSTALLED_TOOLS" | grep -qx "$TOOL"; then
+      echo "⚠️  WARNING: Tool '$TOOL' may not be installed in the sandbox image."
+      echo "   Installed tools: $(echo "$INSTALLED_TOOLS" | tr '\n' ', ' | sed 's/,$//')"
+      echo "   Run setup.sh to add tools."
+      echo ""
     fi
+  fi
+fi
 
-# V2 tool-centric paths
-HOME_DIR="$SANDBOX_DIR/tools/$TOOL/home"
+# Shared home directory for all tools (unified image)
+HOME_DIR="$SANDBOX_DIR/home"
 GIT_SHARED_DIR="$SANDBOX_DIR/shared/git"
+CACHE_DIR="$SANDBOX_DIR/cache"
 
 mkdir -p "$HOME_DIR"
 mkdir -p "$GIT_SHARED_DIR"
+mkdir -p "$CACHE_DIR/npm" "$CACHE_DIR/bun" "$CACHE_DIR/pip" "$CACHE_DIR/playwright-browsers"
+
+# ============================================================================
+# MIGRATION V3: Merge per-tool home directories into unified home
+# ============================================================================
+migrate_to_unified_home() {
+  local marker_file="$SANDBOX_DIR/.migrated-unified-home"
+
+  # Skip if already migrated
+  [[ -f "$marker_file" ]] && return 0
+
+  # Check if any per-tool home directories exist
+  local needs_migration=false
+  for tool_home in "$SANDBOX_DIR"/tools/*/home; do
+    if [[ -d "$tool_home" ]]; then
+      needs_migration=true
+      break
+    fi
+  done
+
+  [[ "$needs_migration" == "false" ]] && { touch "$marker_file"; return 0; }
+
+  echo "🔄 Migrating per-tool home directories to unified home..."
+
+  local migrated_count=0
+  for tool_home in "$SANDBOX_DIR"/tools/*/home; do
+    [[ -d "$tool_home" ]] || continue
+    local tool_name
+    tool_name=$(basename "$(dirname "$tool_home")")
+    echo "  🔄 Migrating tools/$tool_name/home/ → home/"
+
+    # Use cp -rn (no-clobber) - works on macOS and Linux
+    # Falls back to rsync if cp -rn fails (some older systems)
+    # KNOWN ISSUE: glob * doesn't match dotfiles (.nano-brain, .config, etc.)
+    # TODO: fix with dotglob or rsync-first approach
+    if cp -rn "$tool_home/"* "$HOME_DIR/" 2>/dev/null; then
+      ((migrated_count++))
+    elif command -v rsync &>/dev/null; then
+      rsync -a --ignore-existing "$tool_home/" "$HOME_DIR/" 2>/dev/null && ((migrated_count++))
+    else
+      echo "  ⚠️  Could not migrate $tool_name (cp -rn and rsync unavailable)"
+    fi
+  done
+
+  # Create marker file
+  date -Iseconds > "$marker_file" 2>/dev/null || date > "$marker_file"
+
+  if [[ $migrated_count -gt 0 ]]; then
+    echo "✅ Migration complete! Merged $migrated_count tool home directories."
+    echo ""
+    echo "ℹ️  Old per-tool home directories preserved. Run 'npx @kokorolx/ai-sandbox-wrapper clean' to remove them."
+  fi
+}
+
+migrate_to_unified_home
 
 # Build volume mounts for all whitelisted workspaces
 VOLUME_MOUNTS=""
@@ -558,13 +644,47 @@ while IFS= read -r ws; do
   VOLUME_MOUNTS="$VOLUME_MOUNTS -v $ws:$ws:delegated"
 done < "$WORKSPACES_FILE"
 
-# Tool-specific config migration and setup
-# All tool configs now live in HOME_DIR (~/.ai-sandbox/home/$TOOL/)
-# which is mounted as /home/agent in the container
+# Config mount registry for all tools
+# Maps tool name to space-separated config paths (relative to $HOME)
+get_tool_configs() {
+  case "$1" in
+    amp)       echo ".config/amp .local/share/amp" ;;
+    opencode)  echo ".config/opencode .local/share/opencode" ;;
+    claude)    echo ".claude .ccs" ;;
+    openclaw)  echo ".openclaw" ;;
+    droid)     echo ".config/droid" ;;
+    qoder)     echo ".config/qoder" ;;
+    auggie)    echo ".config/auggie" ;;
+    codebuddy) echo ".config/codebuddy" ;;
+    jules)     echo ".config/jules" ;;
+    shai)      echo ".config/shai" ;;
+    gemini)    echo ".config/gemini" ;;
+    aider)     echo ".config/aider .aider" ;;
+    kilo)      echo ".config/kilo" ;;
+    codex)     echo ".config/codex" ;;
+    qwen)      echo ".config/qwen" ;;
+  esac
+}
+
+# All known tools (for fallback)
+ALL_KNOWN_TOOLS="amp opencode claude openclaw droid qoder auggie codebuddy jules shai gemini aider kilo codex qwen"
 
-# Tool-specific config persistence
-# Instead of copying (one-way), we now bind-mount host paths directly
-# to ensure changes inside the container persist to the host.
+# Get list of installed tools from config.json, fallback to all known tools
+get_installed_tools() {
+  local installed
+  if command -v jq &>/dev/null && [[ -f "$AI_SANDBOX_CONFIG" ]]; then
+    installed=$(jq -r '.tools.installed[]? // empty' "$AI_SANDBOX_CONFIG" 2>/dev/null)
+  fi
+  if [[ -z "$installed" ]]; then
+    # Fallback: return all known tools in registry
+    echo "$ALL_KNOWN_TOOLS"
+  else
+    echo "$installed"
+  fi
+}
+
+# Tool config persistence via bind mounts
+# Bind-mount host paths directly to ensure changes persist to the host.
 TOOL_CONFIG_MOUNTS=""
 
 mount_tool_config() {
@@ -582,81 +702,45 @@ mount_tool_config() {
   fi
 }
 
-case "$TOOL" in
-  amp)
-    mount_tool_config "$HOME/.config/amp" ".config/amp"
-    mount_tool_config "$HOME/.local/share/amp" ".local/share/amp"
-    ;;
-  opencode)
-    mount_tool_config "$HOME/.config/opencode" ".config/opencode"
-    mount_tool_config "$HOME/.local/share/opencode" ".local/share/opencode"
-    # Bundle default skills (copy if not already present)
-    AIRUN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-    BUNDLED_SKILLS_DIR="$AIRUN_DIR/../skills"
-    if [[ -d "$BUNDLED_SKILLS_DIR" ]]; then
-      for skill_dir in "$BUNDLED_SKILLS_DIR"/*/; do
-        [[ ! -d "$skill_dir" ]] && continue
-        skill_name=$(basename "$skill_dir")
-        target_dir="$HOME/.config/opencode/skills/$skill_name"
-        if [[ ! -d "$target_dir" ]]; then
-          mkdir -p "$target_dir"
-          cp -r "$skill_dir"* "$target_dir/" 2>/dev/null || true
-        fi
-      done
-    fi
-    ;;
-  openclaw)
-    mount_tool_config "$HOME/.openclaw" ".openclaw"
-    ;;
-  claude)
-    mount_tool_config "$HOME/.claude" ".claude"
-    mount_tool_config "$HOME/.ccs" ".ccs"
-    ;;
-  droid)
-    mount_tool_config "$HOME/.config/droid" ".config/droid"
-    ;;
-  qoder)
-    mount_tool_config "$HOME/.config/qoder" ".config/qoder"
-    ;;
-  auggie)
-    mount_tool_config "$HOME/.config/auggie" ".config/auggie"
-    ;;
-  codebuddy)
-    mount_tool_config "$HOME/.config/codebuddy" ".config/codebuddy"
-    ;;
-  jules)
-    mount_tool_config "$HOME/.config/jules" ".config/jules"
-    ;;
-  shai)
-    mount_tool_config "$HOME/.config/shai" ".config/shai"
-    ;;
-  gemini)
-    mount_tool_config "$HOME/.config/gemini" ".config/gemini"
-    ;;
-  aider)
-    mount_tool_config "$HOME/.config/aider" ".config/aider"
-    mount_tool_config "$HOME/.aider" ".aider"
-    ;;
-  kilo)
-    mount_tool_config "$HOME/.config/kilo" ".config/kilo"
-    ;;
-  codex)
-    mount_tool_config "$HOME/.config/codex" ".config/codex"
-    ;;
-  qwen)
-    mount_tool_config "$HOME/.config/qwen" ".config/qwen"
-    ;;
-esac
+# Mount configs for all installed tools (unified image)
+for tool in $(get_installed_tools); do
+  for cfg_path in $(get_tool_configs "$tool"); do
+    mount_tool_config "$HOME/$cfg_path" "$cfg_path"
+  done
+done
+
+# Bundle OpenCode default skills (if opencode is installed)
+if get_installed_tools | grep -qw "opencode"; then
+  AIRUN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  BUNDLED_SKILLS_DIR="$AIRUN_DIR/../skills"
+  if [[ -d "$BUNDLED_SKILLS_DIR" ]]; then
+    for skill_dir in "$BUNDLED_SKILLS_DIR"/*/; do
+      [[ ! -d "$skill_dir" ]] && continue
+      skill_name=$(basename "$skill_dir")
+      target_dir="$HOME/.config/opencode/skills/$skill_name"
+      if [[ ! -d "$target_dir" ]]; then
+        mkdir -p "$target_dir"
+        cp -r "$skill_dir"* "$target_dir/" 2>/dev/null || true
+      fi
+    done
+  fi
+fi
 
 # Ensure required directories exist in HOME_DIR
 mkdir -p "$HOME_DIR/.config" "$HOME_DIR/.local/share" "$HOME_DIR/.cache" "$HOME_DIR/.bun"
 
-# Project-level config mount (if exists)
-CONFIG_MOUNT=""
-PROJECT_CONFIG="$CURRENT_DIR/.$TOOL.json"
+SHARED_CACHE_MOUNTS="-v $CACHE_DIR/npm:/home/agent/.npm:delegated"
+SHARED_CACHE_MOUNTS="$SHARED_CACHE_MOUNTS -v $CACHE_DIR/bun:/home/agent/.bun/install/cache:delegated"
+SHARED_CACHE_MOUNTS="$SHARED_CACHE_MOUNTS -v $CACHE_DIR/pip:/home/agent/.cache/pip:delegated"
+SHARED_CACHE_MOUNTS="$SHARED_CACHE_MOUNTS -v $CACHE_DIR/playwright-browsers:/opt/playwright-browsers:delegated"
 
-if [[ -f "$PROJECT_CONFIG" ]]; then
-  CONFIG_MOUNT="-v $PROJECT_CONFIG:$CURRENT_DIR/.$TOOL.json:delegated"
+# Project-level config mount (if exists and tool specified)
+CONFIG_MOUNT=""
+if [[ -n "$TOOL" ]]; then
+  PROJECT_CONFIG="$CURRENT_DIR/.$TOOL.json"
+  if [[ -f "$PROJECT_CONFIG" ]]; then
+    CONFIG_MOUNT="-v $PROJECT_CONFIG:$CURRENT_DIR/.$TOOL.json:delegated"
+  fi
 fi
 
 # ============================================================================
@@ -1436,7 +1520,7 @@ generate_container_name() {
   # Generate random 6-character suffix (hex)
   local random_suffix=$(openssl rand -hex 3)
 
-  echo "${TOOL}-${folder_name}-${random_suffix}"
+  echo "${TOOL:-shell}-${folder_name}-${random_suffix}"
 }
 
 # Container name and TTY allocation
@@ -2019,15 +2103,33 @@ fi
 
 # Prepare command based on mode
 ENTRYPOINT_OVERRIDE=""
-if [[ "$SHELL_MODE" == "true" ]]; then
-  # Shell mode: override entrypoint to bash and show welcome message
+if [[ -n "$TOOL" && "$SHELL_MODE" != "true" ]]; then
+  # Direct tool execution: override entrypoint to the tool
+  ENTRYPOINT_OVERRIDE="--entrypoint $TOOL"
+  DOCKER_COMMAND=("${TOOL_ARGS[@]}")
+elif [[ "$SHELL_MODE" == "true" || -z "$TOOL" ]]; then
+  # Shell mode (explicit --shell or no tool specified)
   ENTRYPOINT_OVERRIDE="--entrypoint bash"
-  DOCKER_COMMAND=(
-    "-c"
-    "echo ''; echo '🚀 AI Tool Container - Interactive Shell'; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; echo \"Tool available: ${TOOL}\"; echo 'Run the tool: ${TOOL}'; echo 'Exit container: exit or Ctrl+D'; echo ''; echo \"Additional tools:\"; echo '  - specify (spec-kit): Spec-driven development'; echo '  - uipro (ux-ui-promax): UI/UX design intelligence'; echo '  - openspec: OpenSpec workflow'; echo ''; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; exec bash"
-  )
+  # Build welcome message with installed tools
+  INSTALLED_TOOLS_MSG=""
+  if command -v jq &>/dev/null && [[ -f "$SANDBOX_DIR/config.json" ]]; then
+    INSTALLED_TOOLS_MSG=$(jq -r '.tools.installed // [] | join(", ")' "$SANDBOX_DIR/config.json" 2>/dev/null || echo "")
+  fi
+  if [[ -n "$TOOL" ]]; then
+    # Shell mode with specific tool (ai-run claude --shell)
+    DOCKER_COMMAND=(
+      "-c"
+      "echo ''; echo '🚀 AI Tool Container - Interactive Shell'; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; echo \"Tool available: ${TOOL}\"; echo 'Run the tool: ${TOOL}'; echo 'Exit container: exit or Ctrl+D'; echo ''; echo \"Additional tools:\"; echo '  - specify (spec-kit): Spec-driven development'; echo '  - uipro (ux-ui-promax): UI/UX design intelligence'; echo '  - openspec: OpenSpec workflow'; echo ''; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; exec bash"
+    )
+  else
+    # Shell mode without tool (ai-run with no args)
+    DOCKER_COMMAND=(
+      "-c"
+      "echo ''; echo '🚀 AI Sandbox - Interactive Shell'; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; echo 'Installed tools: ${INSTALLED_TOOLS_MSG:-unknown}'; echo ''; echo 'Run any tool by name: claude, opencode, gemini, etc.'; echo 'Exit: exit or Ctrl+D'; echo ''; echo 'Enhancement tools: specify, uipro, openspec, rtk'; echo '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'; echo ''; exec bash"
+    )
+  fi
 else
-  # Direct mode: use image's default entrypoint with arguments
+  # Fallback: direct mode with image's default entrypoint
   DOCKER_COMMAND=("${TOOL_ARGS[@]}")
 fi
 
@@ -2061,13 +2163,17 @@ fi
 mkdir -p "$HOME_DIR" "$GIT_SHARED_DIR"
 chmod -R u+w "$HOME_DIR" "$GIT_SHARED_DIR" 2>/dev/null || true
 
-# Selective Cache Isolation (Anonymous Volumes)
-# Use anonymous volumes to "hide" host-poisoned node_modules and caches
-# while keeping configurations and auth data.
-CACHE_MOUNTS=""
-if [[ "$TOOL" == "opencode" ]]; then
-  # Isolate heavy caches and node_modules to prevent Bun/Node conflicts
-  CACHE_MOUNTS="-v /home/agent/.npm -v /home/agent/.cache -v /home/agent/.opencode/node_modules"
+if [[ ! -f "$CACHE_DIR/playwright-browsers/.seeded" ]]; then
+  if docker run --rm "$IMAGE" test -d /opt/playwright-browsers 2>/dev/null; then
+    echo "🔄 Seeding shared Playwright browser cache..."
+    docker run --rm -v "$CACHE_DIR/playwright-browsers":/export "$IMAGE" \
+      cp -a /opt/playwright-browsers/. /export/ 2>/dev/null && \
+      touch "$CACHE_DIR/playwright-browsers/.seeded" && \
+      echo "✅ Playwright browsers cached" || \
+      echo "⚠️  Playwright browser seeding failed (will retry next run)"
+  else
+    touch "$CACHE_DIR/playwright-browsers/.seeded"
+  fi
 fi
 
 # Detect display configuration (clipboard integration)
@@ -2145,12 +2251,12 @@ docker run $CONTAINER_NAME --rm $TTY_FLAGS \
   $TOOL_CONFIG_MOUNTS \
   $GIT_MOUNTS \
   $NETWORK_OPTIONS \
-  $CACHE_MOUNTS \
   $DISPLAY_FLAGS \
   $HOST_ACCESS_ARGS \
   $PORT_MAPPINGS \
   $OPENCODE_PASSWORD_ENV \
   -v "$HOME_DIR":/home/agent \
+  $SHARED_CACHE_MOUNTS \
   -w "$CURRENT_DIR" \
   --env-file "$ENV_FILE" \
   -e TERM="$TERM" \

package/bin/cli.js

@@ -23,6 +23,7 @@ Commands:
   setup                 Run interactive setup (configure workspaces, select tools)
   update                Interactive menu to manage config (workspaces, git, networks)
   clean                 Interactive cleanup for caches/configs
+  clean cache [type]    Clear shared package caches (npm, bun, pip, playwright-browsers)
   config show [--json]         Display current global configuration
   config tool <tool> [--show]  Display host paths and config for a specific tool
 
@@ -326,9 +327,9 @@ async function runConfigTool(toolName, showContent) {
     process.exit(1);
   }
 
-  const toolHome = path.join(SANDBOX_DIR, 'tools', toolName, 'home');
+  const toolHome = path.join(SANDBOX_DIR, 'home');
   console.log(`\n🔍 Sandbox Configuration for: ${toolName}`);
-  console.log(`Host Home:  ${toolHome}`);
+  console.log(`Sandbox Home: ${toolHome}`);
 
   if (!fs.existsSync(toolHome)) {
     console.log('Status:     ⚠️  Not yet initialized (folder missing on host)');
@@ -1259,6 +1260,45 @@ async function manageNetworksMenu(rl) {
   }
 }
 
+// ============================================================================
+// CLEAN CACHE COMMAND (non-interactive)
+// ============================================================================
+const CACHE_TYPES = ['npm', 'bun', 'pip', 'playwright-browsers']
+
+function runCleanCache(cacheType) {
+  const cacheDir = path.join(SANDBOX_DIR, 'cache')
+
+  if (cacheType && !CACHE_TYPES.includes(cacheType)) {
+    console.error(`❌ Unknown cache type: ${cacheType}`)
+    console.error(`Valid types: ${CACHE_TYPES.join(', ')}`)
+    process.exit(1)
+  }
+
+  const targets = cacheType ? [cacheType] : CACHE_TYPES
+
+  let totalFreed = 0
+  for (const t of targets) {
+    const targetPath = path.join(cacheDir, t)
+    if (!pathExists(targetPath)) {
+      console.log(`  ⏭  ${t}/ (not found)`)
+      continue
+    }
+    const size = getPathSize(targetPath)
+    const sizeNum = typeof size === 'number' ? size : 0
+    try {
+      fs.rmSync(targetPath, { recursive: true, force: true })
+      fs.mkdirSync(targetPath, { recursive: true })
+      totalFreed += sizeNum
+      console.log(`  ✓ ${t}/ cleared (${formatBytes(sizeNum)})`)
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err)
+      console.error(`  ❌ ${t}/: ${msg}`)
+    }
+  }
+
+  console.log(`\n🧹 Freed ${formatBytes(totalFreed)}`)
+}
+
 // Parse subcommand and options
 const subCommand = positionalArgs[1];
 const subArg = positionalArgs[2];
@@ -1286,11 +1326,15 @@ switch (command) {
     });
     break;
   case 'clean':
-    runClean().catch((err) => {
-      const message = err && err.message ? err.message : String(err);
-      console.error('❌ Cleanup failed:', message);
-      process.exit(1);
-    });
+    if (subCommand === 'cache') {
+      runCleanCache(subArg)
+    } else {
+      runClean().catch((err) => {
+        const message = err && err.message ? err.message : String(err)
+        console.error('❌ Cleanup failed:', message)
+        process.exit(1)
+      })
+    }
     break;
   case 'config':
     if (subCommand === 'show') {

package/dockerfiles/base/Dockerfile

@@ -10,6 +10,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends     git     cur
 
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null     && apt-get update     && apt-get install -y gh     && rm -rf /var/lib/apt/lists/*
 
+# Install bun (used by most AI tool install scripts)
+RUN npm install -g bun
+
 # Install pnpm globally using npm (not bun, for stability)
 RUN npm install -g pnpm
 
@@ -40,6 +43,10 @@ RUN mkdir -p /usr/local/lib/openspec && \
     chmod +x /usr/local/bin/openspec
 # Install RTK - token optimizer for AI coding agents (built from source)
 COPY --from=rtk-builder /usr/local/cargo/bin/rtk /usr/local/bin/rtk
+# Install RTK OpenCode skills (auto-discovered by OpenCode agents)
+RUN mkdir -p /home/agent/.config/opencode/skills/rtk /home/agent/.config/opencode/skills/rtk-setup
+COPY skills/rtk/SKILL.md /home/agent/.config/opencode/skills/rtk/SKILL.md
+COPY skills/rtk-setup/SKILL.md /home/agent/.config/opencode/skills/rtk-setup/SKILL.md
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libglib2.0-0 \
     libnspr4 \

package/dockerfiles/base/skills/rtk/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rtk
+description: "Token optimizer for AI coding agents. Wraps common CLI commands with rtk to reduce LLM token consumption by 60-90%."
+compatibility: "OpenCode with RTK binary installed"
+metadata:
+  author: Sisyphus
+  version: "1.0.0"
+---
+
+# RTK — Rust Token Killer
+
+**Purpose**: Reduce token consumption by 60-90% on shell commands. RTK filters and compresses command output before it reaches your context.
+
+## When This Skill Activates
+
+This skill is loaded automatically. Once active, **always** prefix supported commands with `rtk`.
+
+## Command Mappings (MANDATORY)
+
+When running shell commands via Bash tool, use `rtk` prefix for these commands:
+
+| Instead of | Use | Savings |
+|-----------|-----|---------|
+| `git status` | `rtk git status` | ~80% |
+| `git diff` | `rtk git diff` | ~75% |
+| `git log` | `rtk git log` | ~80% |
+| `git add/commit/push/pull` | `rtk git add/commit/push/pull` | ~90% |
+| `ls` / `ls -la` | `rtk ls` | ~80% |
+| `cat file` | `rtk read file` | ~70% |
+| `grep pattern .` | `rtk grep pattern .` | ~80% |
+| `rg pattern` | `rtk grep pattern .` | ~80% |
+| `npm test` / `cargo test` / `pytest` | `rtk test <cmd>` | ~90% |
+| `npm run build` / `cargo build` | `rtk err <cmd>` | ~80% |
+| `gh pr list/view` | `rtk gh pr list/view` | ~70% |
+| `docker ps` | `rtk docker ps` | ~80% |
+| `eslint` / `tsc` | `rtk lint` / `rtk tsc` | ~80% |
+
+## Searching Inside `node_modules` / Ignored Directories
+
+By default, `rtk grep` respects `.gitignore` rules — meaning `node_modules`, `.nuxt`, `dist`, etc. are **excluded**. This is the right behavior 99% of the time.
+
+When you **need** to search inside ignored directories (debugging a library, checking an API signature, tracing a dependency bug):
+
+```bash
+# Search all files including node_modules (--no-ignore bypasses .gitignore)
+rtk grep "defineStore" . --no-ignore
+
+# Search a specific package only (combine --no-ignore with --glob)
+rtk grep "defineStore" . --no-ignore --glob 'node_modules/pinia/**'
+```
+
+**What does NOT work:**
+- `rtk grep "pattern" node_modules/pinia/` — still excluded even with direct path
+- `rtk grep "pattern" . --glob 'node_modules/**'` — glob alone doesn't override .gitignore
+
+**Key flag: `--no-ignore`** — this is the ONLY way to search ignored directories with rtk grep.
+
+### Other useful `rtk grep` flags
+
+```bash
+rtk grep "pattern" . -t ts          # Filter by file type (ts, py, rust, etc.)
+rtk grep "pattern" . -m 100         # Increase max results (default: 50)
+rtk grep "pattern" . -u             # Ultra-compact mode (even fewer tokens)
+rtk grep "pattern" . -l 120         # Max line length before truncation (default: 80)
+```
+
+## Commands to NOT Wrap
+
+Do NOT prefix these with `rtk` (unsupported or counterproductive):
+
+- `npx`, `npm install`, `pip install` (package managers)
+- `node`, `python3`, `ruby` (interpreters)
+- `nano-brain`, `openspec`, `opencode` (custom tools)
+- Heredocs (`<<EOF`)
+- Piped commands (`cmd1 | cmd2`) — wrap only the first command if applicable
+- Commands already prefixed with `rtk`
+
+## How RTK Works
+
+```
+Without RTK:  git status → 50 lines raw output → 2,000 tokens
+With RTK:     rtk git status → "3 modified, 1 untracked ✓" → 200 tokens
+```
+
+RTK runs the real command, then filters/compresses the output. The agent sees a compact summary instead of verbose raw output.
+
+## Detection
+
+Before using RTK commands, verify it's installed:
+```bash
+rtk --version
+```
+
+If `rtk` is not found, skip this skill — run commands normally without the `rtk` prefix.
+
+## Token Savings Reference
+
+Typical 30-min coding session:
+- Without RTK: ~150,000 tokens
+- With RTK: ~45,000 tokens
+- **Savings: ~70%**
+
+Biggest wins: test output (`rtk test` — 90%), git operations (`rtk git` — 80%), file reading (`rtk read` — 70%).