@jgamaraalv/ts-dev-kit 3.0.1 → 3.1.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
     "url": "https://github.com/jgamaraalv"
   },
   "metadata": {
-    "description": "15 agents and 21 skills for TypeScript fullstack development with Claude Code"
+    "description": "15 agents and 22 skills for TypeScript fullstack development with Claude Code"
   },
   "plugins": [
     {
       "name": "ts-dev-kit",
       "source": "./",
-      "description": "15 specialized agents and 21 skills for TypeScript fullstack development",
-      "version": "3.0.1",
+      "description": "15 specialized agents and 22 skills for TypeScript fullstack development",
+      "version": "3.1.1",
       "author": {
         "name": "jgamaraalv"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ts-dev-kit",
-  "version": "3.0.1",
-  "description": "15 specialized agents and 21 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
+  "version": "3.1.1",
+  "description": "15 specialized agents and 22 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
   "author": {
     "name": "jgamaraalv",
     "url": "https://github.com/jgamaraalv"

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.1] - 2026-02-27
+
+### Fixed
+
+- `/yolo` firewall script: add resilient fallback for Docker Desktop environments where `ipset` kernel module is unavailable — falls back to iptables-only rules, `getent` DNS resolution, and direct GitHub domain resolution; full diagnostic log at `/tmp/firewall-init.log`
+
+## [3.1.0] - 2026-02-27
+
+### Added
+
+- `/yolo` skill: devcontainer setup and launch workflow for running Claude Code with `--dangerously-skip-permissions` in a secure, sandboxed environment — detects existing devcontainer, checks Docker status, scaffolds the Claude Code reference `.devcontainer/` (Dockerfile, firewall, config), starts Docker if needed, and opens VS Code to launch the container
+- Dynamic context injection to `/yolo`: project root, devcontainer presence, Docker daemon status, Docker and VS Code installation are pre-injected before Claude receives the prompt
+
 ## [3.0.1] - 2026-02-27
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # ts-dev-kit
 
-> 15 specialized agents + 21 curated skills for TypeScript fullstack development
+> 15 specialized agents + 22 curated skills for TypeScript fullstack development
 
 [![npm version](https://img.shields.io/npm/v/@jgamaraalv/ts-dev-kit)](https://www.npmjs.com/package/@jgamaraalv/ts-dev-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -30,7 +30,7 @@
 | typescript-pro          | Generics, type inference, conditional types             |
 | ux-optimizer            | User flows, form UX, friction reduction                 |
 
-### Skills (21)
+### Skills (22)
 
 | Skill                  | Slug                      | Domain                                            |
 | ---------------------- | ------------------------- | ------------------------------------------------- |
@@ -55,6 +55,7 @@
 | TanStack Query         | `/tanstack-query`         | React Query v5, caching, SSR/hydration            |
 | TypeScript Conventions | `/typescript-conventions` | Strict config, patterns, best practices           |
 | UI/UX Guidelines       | `/ui-ux-guidelines`       | Accessibility, layout, forms                      |
+| Yolo                   | `/yolo`                   | Devcontainer setup for autonomous Claude Code     |
 
 ---
 
@@ -206,6 +207,7 @@ Several skills use the `!`command`` syntax to pre-inject live data before Claude
 | `/conventional-commits` | Staged diff summary, full staged diff, last 8 commit messages |
 | `/debug` | Last 10 git commits, working tree status |
 | `/codebase-adapter` | Working directory, lockfile, installed agents, MCP servers, `package.json` |
+| `/yolo` | Project root, devcontainer presence, Docker status, VS Code installation |
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jgamaraalv/ts-dev-kit",
-  "version": "3.0.1",
-  "description": "Claude Code plugin: 15 agents + 21 skills for TypeScript fullstack development",
+  "version": "3.1.1",
+  "description": "Claude Code plugin: 15 agents + 22 skills for TypeScript fullstack development",
   "author": "jgamaraalv",
   "license": "MIT",
   "repository": {

package/skills/debug/SKILL.md

@@ -22,6 +22,10 @@ allowed-tools: Bash(git *)
 - "Debug the notification queue — jobs are stuck"
 </trigger_examples>
 
+<task>
+$ARGUMENTS
+</task>
+
 <workflow>
 Follow each phase in order. Each one feeds the next.
 
@@ -233,7 +237,3 @@ When complete, produce a debug report using the template in [template.md](templa
 
 Do not add explanations, caveats, or follow-up suggestions unless the user asks.
 </output>
-
-<task>
-$ARGUMENTS
-</task>

package/skills/yolo/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: yolo
+description: "Sets up and launches a Claude Code devcontainer with --dangerously-skip-permissions for fully autonomous, unattended operation inside a sandboxed environment. Use when: (1) user wants to run Claude Code without permission prompts, (2) setting up a secure development container for autonomous coding, (3) user says 'yolo', 'yolo mode', 'run without permissions', 'autonomous mode', 'skip permissions safely', or 'devcontainer setup'."
+argument-hint: "[optional: path to project root — defaults to current directory]"
+allowed-tools: Bash(docker *), Bash(ls *), Bash(cat *), Bash(cp *), Bash(mkdir *), Bash(which *), Bash(open *), Bash(code *), Bash(command *)
+---
+
+<live_context>
+**Project root:**
+!`pwd`
+
+**Devcontainer present:**
+!`ls -la .devcontainer/devcontainer.json 2>/dev/null && echo "YES" || echo "NO"`
+
+**Docker daemon status:**
+!`docker info --format '{{.ServerVersion}}' 2>/dev/null && echo "RUNNING" || echo "NOT RUNNING"`
+
+**Docker Desktop installed:**
+!`command -v docker 2>/dev/null || echo "NOT FOUND"`
+
+**VS Code installed:**
+!`command -v code 2>/dev/null || echo "NOT FOUND"`
+</live_context>
+
+<trigger_examples>
+- "yolo"
+- "Enter yolo mode"
+- "Set up a devcontainer so Claude can run autonomously"
+- "I want to run Claude Code without permission prompts"
+- "Skip permissions safely with a devcontainer"
+- "Set up autonomous mode"
+</trigger_examples>
+
+<system>
+You are a devcontainer setup specialist. Your goal is to get the user into a secure, sandboxed devcontainer running `claude --dangerously-skip-permissions` as quickly as possible. You follow a strict decision tree and never skip safety checks.
+
+**IMPORTANT SECURITY NOTE:** While the devcontainer provides substantial protections (network firewall, isolation), it is NOT immune to all attacks. Only use devcontainers with **trusted repositories**. The `--dangerously-skip-permissions` flag gives Claude full access to everything inside the container, including credentials mounted into it. Always inform the user of this trade-off.
+</system>
+
+<task>
+$ARGUMENTS
+</task>
+
+<workflow>
+Follow this decision tree strictly. Each phase gates the next.
+
+```
+START
+  │
+  ├─ Phase 1: Detect devcontainer
+  │    ├─ EXISTS → Phase 2
+  │    └─ MISSING → Phase 5 (install) → Phase 2
+  │
+  ├─ Phase 2: Check Docker
+  │    ├─ RUNNING → Phase 3
+  │    └─ NOT RUNNING → Phase 4 (start Docker) → Phase 3
+  │
+  ├─ Phase 3: Launch devcontainer
+  │    └─ claude --dangerously-skip-permissions
+  │
+  ├─ Phase 4: Start Docker
+  │    └─ Start Docker Desktop/daemon → Phase 3
+  │
+  └─ Phase 5: Install devcontainer
+       └─ Scaffold .devcontainer/ → Phase 2
+```
+
+<phase_1_detect>
+
+## Phase 1 — Detect devcontainer
+
+Check whether `.devcontainer/devcontainer.json` exists in the project root.
+
+1. Read the `<live_context>` above for the pre-injected detection result.
+2. If **YES** — announce to the user and proceed to Phase 2:
+
+> **DEVCONTAINER DETECTED** — `.devcontainer/` found. Checking Docker status...
+
+3. If **NO** — announce and proceed to Phase 5:
+
+> **NO DEVCONTAINER FOUND** — I'll set one up using the Claude Code reference implementation.
+
+</phase_1_detect>
+
+<phase_2_check_docker>
+
+## Phase 2 — Check Docker
+
+Verify the Docker daemon is running and accessible.
+
+1. Read the `<live_context>` above for the pre-injected Docker status.
+2. If `docker` command is **NOT FOUND**:
+
+> **DOCKER NOT INSTALLED** — Docker Desktop is required for devcontainers. Please install it from https://www.docker.com/products/docker-desktop/ and re-run `/yolo`.
+
+Stop here. Do not proceed.
+
+3. If Docker is **RUNNING** — proceed to Phase 3:
+
+> **DOCKER RUNNING** (version X.X.X) — Ready to launch devcontainer.
+
+4. If Docker is **NOT RUNNING** — proceed to Phase 4.
+
+</phase_2_check_docker>
+
+<phase_3_launch>
+
+## Phase 3 — Launch devcontainer
+
+Open the project in VS Code with the devcontainer.
+
+**Prerequisites check:**
+
+1. Verify VS Code is installed (`command -v code`).
+2. If VS Code is not installed, inform the user:
+
+> **VS Code is required** for devcontainer support. Install it from https://code.visualstudio.com/ and re-run `/yolo`.
+
+Stop here. Do not proceed.
+
+3. Ensure the Dev Containers extension is installed:
+
+```bash
+code --install-extension ms-vscode-remote.remote-containers
+```
+
+This is idempotent — if already installed, VS Code simply reports it and moves on.
+
+**Launch sequence:**
+
+1. Open the project in VS Code:
+
+```bash
+code .
+```
+
+2. Instruct the user:
+
+> **LAUNCHING DEVCONTAINER**
+>
+> VS Code is opening your project. Follow these steps:
+>
+> 1. VS Code should prompt **"Reopen in Container"** — click it.
+>    - If no prompt appears: open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) → type **"Dev Containers: Reopen in Container"** → select it.
+> 2. Wait for the container to build (first time takes 2-5 minutes as it installs Node.js 20, Claude Code, ZSH, and configures the firewall).
+> 3. Once inside the container, open a terminal and run:
+>    ```
+>    claude --dangerously-skip-permissions
+>    ```
+>
+> **What's happening under the hood:**
+>
+> - The container runs Node.js 20 with Claude Code pre-installed
+> - A firewall restricts outbound traffic to: npm registry, GitHub, Claude API, Sentry, and VS Code marketplace only
+> - All other internet access is blocked (verified on startup)
+> - Your project is mounted at `/workspace`
+> - Shell history and Claude config persist between container restarts
+>
+> **Security trade-off:** `--dangerously-skip-permissions` means Claude can execute ANY command inside the container without asking. The firewall and container isolation are your safety net. Only use this with trusted code.
+
+</phase_3_launch>
+
+<phase_4_start_docker>
+
+## Phase 4 — Start Docker
+
+The Docker daemon is installed but not running.
+
+**macOS:**
+
+```bash
+open -a Docker
+```
+
+**Linux:**
+
+```bash
+sudo systemctl start docker
+```
+
+After issuing the start command:
+
+1. Wait for Docker to become ready (poll up to 30 seconds):
+
+```bash
+for i in $(seq 1 15); do
+  docker info --format '{{.ServerVersion}}' 2>/dev/null && break
+  sleep 2
+done
+```
+
+2. Re-verify Docker is running:
+
+```bash
+docker info --format '{{.ServerVersion}}' 2>/dev/null
+```
+
+3. If Docker started successfully — proceed to Phase 3:
+
+> **DOCKER STARTED** — Docker daemon is now running. Launching devcontainer...
+
+4. If Docker failed to start after 30 seconds:
+
+> **DOCKER FAILED TO START** — Please start Docker Desktop manually and re-run `/yolo`.
+
+Stop here.
+
+</phase_4_start_docker>
+
+<phase_5_install_devcontainer>
+
+## Phase 5 — Install devcontainer
+
+Scaffold the `.devcontainer/` directory with the Claude Code reference implementation.
+
+### Step 1 — Create directory
+
+```bash
+mkdir -p .devcontainer
+```
+
+### Step 2 — Create `devcontainer.json`
+
+Write the file using the reference config. See [references/devcontainer-json.md](references/devcontainer-json.md) for the full file content.
+
+Key settings:
+
+- Name: `"Claude Code Sandbox"`
+- Dockerfile build with Node.js 20
+- `NET_ADMIN` + `NET_RAW` capabilities (required for firewall)
+- Claude Code VS Code extension pre-installed
+- Volume mounts for bash history and Claude config persistence
+- Firewall initialization via `postStartCommand`
+- Workspace mounted at `/workspace`
+
+### Step 3 — Create `Dockerfile`
+
+Write the file using the reference Dockerfile. See [references/dockerfile.md](references/dockerfile.md) for the full file content.
+
+Key features:
+
+- Base: `node:20`
+- Installs: git, ZSH, fzf, gh CLI, iptables/ipset, nano, vim
+- Installs `@anthropic-ai/claude-code` globally
+- Sets up non-root `node` user
+- Configures ZSH with Powerlevel10k theme
+- Copies and configures firewall script with sudo access
+
+### Step 4 — Create `init-firewall.sh`
+
+Write the file using the reference firewall script. See [references/init-firewall.sh.md](references/init-firewall.sh.md) for the full file content.
+
+Key security features:
+
+- Default-deny policy (DROP all INPUT, OUTPUT, FORWARD)
+- Whitelisted outbound only: npm registry, GitHub (dynamic IP fetch), Claude API, Sentry, StatsIG, VS Code marketplace
+- DNS and SSH allowed
+- Localhost and host network allowed
+- Startup verification: confirms `example.com` is blocked and `api.github.com` is reachable
+- Docker DNS rules preserved
+- Falls back to iptables-only rules if `ipset` kernel module is unavailable (common on Docker Desktop for Mac)
+- Full diagnostic log at `/tmp/firewall-init.log` for troubleshooting
+
+### Step 5 — Add `.devcontainer` to `.gitignore` (optional)
+
+Check if `.gitignore` exists and whether `.devcontainer/` is already listed. If not, ask the user:
+
+> **Should I add `.devcontainer/` to `.gitignore`?**
+>
+> - **Yes** — keep devcontainer config local to your machine
+> - **No** — commit it so the whole team can use it (recommended for teams)
+
+### Step 6 — Verify installation
+
+```bash
+ls -la .devcontainer/
+cat .devcontainer/devcontainer.json | head -5
+```
+
+Announce completion:
+
+> **DEVCONTAINER INSTALLED** — `.devcontainer/` is ready with Dockerfile, firewall script, and configuration. Proceeding to check Docker...
+
+Return to Phase 2.
+
+</phase_5_install_devcontainer>
+
+</workflow>
+
+<customization_notes>
+
+## Customizing the devcontainer
+
+After installation, the user may want to customize:
+
+**Adding allowed domains to the firewall:**
+Edit `.devcontainer/init-firewall.sh` and add domains to the `for domain in` loop:
+
+```bash
+for domain in \
+    "registry.npmjs.org" \
+    "api.anthropic.com" \
+    "your-custom-domain.com" \   # <-- add here
+    ...
+```
+
+**Adding VS Code extensions:**
+Edit `.devcontainer/devcontainer.json` → `customizations.vscode.extensions[]`:
+
+```json
+"extensions": [
+    "anthropic.claude-code",
+    "your-extension.id"
+]
+```
+
+**Changing Node.js version:**
+Edit `.devcontainer/Dockerfile` — change the `FROM` line:
+
+```dockerfile
+FROM node:22
+```
+
+**Adding project-specific dependencies:**
+Add `RUN` commands to the Dockerfile before the `USER node` line:
+
+```dockerfile
+RUN apt-get update && apt-get install -y your-package
+```
+
+</customization_notes>

package/skills/yolo/references/devcontainer-json.md

@@ -0,0 +1,74 @@
+# devcontainer.json — Reference
+
+Write this file to `.devcontainer/devcontainer.json`:
+
+```json
+{
+  "name": "Claude Code Sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Los_Angeles}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": [
+    "--cap-add=NET_ADMIN",
+    "--cap-add=NET_RAW"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "node",
+  "mounts": [
+    "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace",
+  "postStartCommand": "sudo /usr/local/bin/init-firewall.sh 2>&1 | tee /tmp/firewall-init.log",
+  "waitFor": "postStartCommand"
+}
+```
+
+## Key settings explained
+
+| Setting | Purpose |
+|---------|---------|
+| `runArgs: --cap-add=NET_ADMIN,NET_RAW` | Required for the firewall script to configure iptables |
+| `remoteUser: node` | Runs as non-root for security |
+| `mounts` (bashhistory, config) | Persists shell history and Claude config between container restarts |
+| `postStartCommand` | Initializes the firewall on every container start |
+| `waitFor: postStartCommand` | Ensures firewall is active before VS Code connects |
+| `workspaceMount` | Binds the local project into `/workspace` with delegated consistency for performance |

package/skills/yolo/references/dockerfile.md

@@ -0,0 +1,108 @@
+# Dockerfile — Reference
+
+Write this file to `.devcontainer/Dockerfile`:
+
+```dockerfile
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
+USER node
+```
+
+## What this Dockerfile provides
+
+| Layer | Details |
+|-------|---------|
+| **Base image** | Node.js 20 (LTS) |
+| **Dev tools** | git, ZSH, fzf, gh CLI, jq, nano, vim, delta (git diff) |
+| **Network tools** | iptables, ipset, iproute2, dnsutils, aggregate (for firewall) |
+| **User** | Non-root `node` user with sudo for firewall script only |
+| **Shell** | ZSH with Powerlevel10k theme, fzf key bindings |
+| **Claude Code** | Installed globally via npm (version configurable via build arg) |
+| **Firewall** | `init-firewall.sh` copied and configured with passwordless sudo |

package/skills/yolo/references/init-firewall.sh.md

@@ -0,0 +1,292 @@
+# init-firewall.sh — Reference
+
+Write this file to `.devcontainer/init-firewall.sh`:
+
+```bash
+#!/bin/bash
+set -uo pipefail  # Strict vars and pipelines, but handle errors manually
+IFS=$'\n\t'
+
+LOG="/tmp/firewall-init.log"
+exec > >(tee -a "$LOG") 2>&1
+echo "=== Firewall init started at $(date -u) ==="
+
+# --- Diagnostics -----------------------------------------------------------
+echo "--- Pre-flight checks ---"
+HAVE_IPTABLES=false
+HAVE_IPSET=false
+
+if iptables -L -n >/dev/null 2>&1; then
+    HAVE_IPTABLES=true
+    echo "[OK] iptables is functional"
+else
+    echo "[FAIL] iptables is NOT functional — firewall cannot be configured"
+    echo "Hint: ensure --cap-add=NET_ADMIN is set in devcontainer.json runArgs"
+    exit 1
+fi
+
+if ipset list >/dev/null 2>&1 || ipset create _test hash:net 2>/dev/null; then
+    ipset destroy _test 2>/dev/null || true
+    HAVE_IPSET=true
+    echo "[OK] ipset is functional"
+else
+    echo "[WARN] ipset is NOT functional — falling back to iptables-only rules"
+fi
+
+if command -v dig >/dev/null 2>&1; then
+    echo "[OK] dig is available"
+else
+    echo "[WARN] dig not found — DNS resolution will use getent"
+fi
+
+if command -v aggregate >/dev/null 2>&1; then
+    echo "[OK] aggregate is available"
+else
+    echo "[WARN] aggregate not found — GitHub CIDRs will be added individually"
+fi
+
+# --- Helper: resolve domain to IPs ----------------------------------------
+resolve_domain() {
+    local domain="$1"
+    local ips=""
+    if command -v dig >/dev/null 2>&1; then
+        ips=$(dig +noall +answer +short A "$domain" 2>/dev/null | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$')
+    fi
+    if [ -z "$ips" ] && command -v getent >/dev/null 2>&1; then
+        ips=$(getent ahostsv4 "$domain" 2>/dev/null | awk '{print $1}' | sort -u | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$')
+    fi
+    echo "$ips"
+}
+
+# --- 1. Preserve Docker DNS -----------------------------------------------
+echo "--- Preserving Docker DNS rules ---"
+DOCKER_DNS_RULES=$(iptables-save -t nat 2>/dev/null | grep "127\.0\.0\.11" || true)
+
+# --- 2. Flush existing rules -----------------------------------------------
+echo "--- Flushing existing rules ---"
+iptables -F  || true
+iptables -X  || true
+iptables -t nat -F    || true
+iptables -t nat -X    || true
+iptables -t mangle -F || true
+iptables -t mangle -X || true
+if [ "$HAVE_IPSET" = true ]; then
+    ipset destroy allowed-domains 2>/dev/null || true
+fi
+
+# --- 3. Restore Docker DNS -------------------------------------------------
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | while read -r rule; do
+        iptables -t nat $rule 2>/dev/null || true
+    done
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# --- 4. Base rules (DNS, SSH, localhost) ------------------------------------
+echo "--- Setting base rules ---"
+# Outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
+# Inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+iptables -A INPUT -p tcp --sport 53 -j ACCEPT
+# Outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# --- 5. Host network -------------------------------------------------------
+HOST_IP=$(ip route 2>/dev/null | grep default | head -1 | awk '{print $3}')
+if [ -n "$HOST_IP" ]; then
+    HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/16/")
+    echo "Host network: $HOST_NETWORK (via $HOST_IP)"
+    iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+    iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+else
+    echo "[WARN] Could not detect host IP — allowing RFC1918 ranges for Docker connectivity"
+    iptables -A INPUT -s 172.16.0.0/12 -j ACCEPT
+    iptables -A OUTPUT -d 172.16.0.0/12 -j ACCEPT
+    iptables -A INPUT -s 192.168.0.0/16 -j ACCEPT
+    iptables -A OUTPUT -d 192.168.0.0/16 -j ACCEPT
+    iptables -A INPUT -s 10.0.0.0/8 -j ACCEPT
+    iptables -A OUTPUT -d 10.0.0.0/8 -j ACCEPT
+fi
+
+# --- 6. Allowed domains ----------------------------------------------------
+ALLOWED_DOMAINS=(
+    "registry.npmjs.org"
+    "api.anthropic.com"
+    "sentry.io"
+    "statsig.anthropic.com"
+    "statsig.com"
+    "marketplace.visualstudio.com"
+    "vscode.blob.core.windows.net"
+    "update.code.visualstudio.com"
+)
+
+if [ "$HAVE_IPSET" = true ]; then
+    # ---- ipset mode (preferred) ----
+    echo "--- Building ipset allowlist ---"
+    ipset create allowed-domains hash:net
+
+    # GitHub dynamic IPs
+    echo "Fetching GitHub IP ranges..."
+    gh_ranges=$(curl -sf --connect-timeout 10 https://api.github.com/meta 2>/dev/null || true)
+    if [ -n "$gh_ranges" ] && echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null 2>&1; then
+        if command -v aggregate >/dev/null 2>&1; then
+            while read -r cidr; do
+                [[ "$cidr" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$ ]] && ipset add allowed-domains "$cidr" 2>/dev/null || true
+            done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q 2>/dev/null)
+        else
+            while read -r cidr; do
+                [[ "$cidr" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$ ]] && ipset add allowed-domains "$cidr" 2>/dev/null || true
+            done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]')
+        fi
+        echo "[OK] GitHub IP ranges added"
+    else
+        echo "[WARN] Could not fetch GitHub IPs — resolving github.com directly"
+        for gh_domain in "github.com" "api.github.com" "raw.githubusercontent.com" "objects.githubusercontent.com"; do
+            ips=$(resolve_domain "$gh_domain")
+            while read -r ip; do
+                [ -n "$ip" ] && ipset add allowed-domains "$ip" 2>/dev/null || true
+            done <<< "$ips"
+        done
+    fi
+
+    # Other allowed domains
+    for domain in "${ALLOWED_DOMAINS[@]}"; do
+        echo "Resolving $domain..."
+        ips=$(resolve_domain "$domain")
+        if [ -z "$ips" ]; then
+            echo "[WARN] Failed to resolve $domain — skipping"
+            continue
+        fi
+        while read -r ip; do
+            [ -n "$ip" ] && ipset add allowed-domains "$ip" 2>/dev/null || true
+        done <<< "$ips"
+    done
+
+    # Apply ipset match rule
+    iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+else
+    # ---- iptables-only mode (fallback) ----
+    echo "--- Building iptables allowlist (no ipset) ---"
+
+    # GitHub IPs
+    echo "Fetching GitHub IP ranges..."
+    gh_ranges=$(curl -sf --connect-timeout 10 https://api.github.com/meta 2>/dev/null || true)
+    if [ -n "$gh_ranges" ] && echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null 2>&1; then
+        while read -r cidr; do
+            [[ "$cidr" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$ ]] && \
+                iptables -A OUTPUT -d "$cidr" -j ACCEPT 2>/dev/null || true
+        done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]')
+        echo "[OK] GitHub IP ranges added via iptables"
+    else
+        echo "[WARN] Could not fetch GitHub IPs — resolving github.com directly"
+        for gh_domain in "github.com" "api.github.com" "raw.githubusercontent.com" "objects.githubusercontent.com"; do
+            ips=$(resolve_domain "$gh_domain")
+            while read -r ip; do
+                [ -n "$ip" ] && iptables -A OUTPUT -d "$ip" -j ACCEPT 2>/dev/null || true
+            done <<< "$ips"
+        done
+    fi
+
+    # Other allowed domains
+    for domain in "${ALLOWED_DOMAINS[@]}"; do
+        echo "Resolving $domain..."
+        ips=$(resolve_domain "$domain")
+        if [ -z "$ips" ]; then
+            echo "[WARN] Failed to resolve $domain — skipping"
+            continue
+        fi
+        while read -r ip; do
+            [ -n "$ip" ] && iptables -A OUTPUT -d "$ip" -j ACCEPT 2>/dev/null || true
+        done <<< "$ips"
+    done
+fi
+
+# --- 7. Default-deny policies ----------------------------------------------
+echo "--- Applying default-deny policies ---"
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# Allow established connections
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Reject everything else with immediate feedback
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+# --- 8. Verification -------------------------------------------------------
+echo "--- Verifying firewall ---"
+VERIFIED=true
+
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "[FAIL] Firewall verification failed — reached https://example.com (should be blocked)"
+    VERIFIED=false
+else
+    echo "[OK] https://example.com is blocked as expected"
+fi
+
+if curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "[OK] https://api.github.com is reachable as expected"
+else
+    echo "[WARN] https://api.github.com is not reachable — GitHub IPs may have changed"
+    echo "       Claude Code will still work, but git operations may fail"
+fi
+
+if [ "$VERIFIED" = false ]; then
+    echo "=== FIREWALL VERIFICATION FAILED ==="
+    exit 1
+fi
+
+echo "=== Firewall configured successfully ==="
+echo "Mode: $([ "$HAVE_IPSET" = true ] && echo 'ipset' || echo 'iptables-only')"
+echo "Log: $LOG"
+```
+
+## Key improvements over the original
+
+| Issue | Original behavior | Improved behavior |
+|-------|-------------------|-------------------|
+| `ipset` not available | Fatal crash | Falls back to iptables-only rules |
+| `aggregate` not available | Fatal crash | Adds CIDRs individually without aggregation |
+| `dig` not available | Fatal crash | Falls back to `getent ahostsv4` |
+| GitHub API unreachable | Fatal crash | Resolves github.com/api.github.com directly |
+| Domain resolution fails | Fatal crash | Skips domain with warning, continues |
+| Host IP detection fails | Fatal crash | Allows all RFC1918 ranges as fallback |
+| Docker DNS restore fails | Silent + potential crash | Handles per-rule with `|| true` |
+| No diagnostic output | Blind exit code 1 | Full log at `/tmp/firewall-init.log` |
+| GitHub unreachable after setup | Fatal crash | Warning only (Claude API is the critical path) |
+
+## Firewall rules summary
+
+| Rule | Direction | Purpose |
+|------|-----------|---------|
+| DNS (UDP/TCP 53) | Outbound | Domain name resolution |
+| SSH (TCP 22) | Outbound | Git over SSH |
+| Localhost | Both | Container-internal communication |
+| Host network | Both | Docker host ↔ container communication |
+| GitHub IPs | Outbound | Git operations, GitHub API (dynamically fetched or resolved) |
+| npm registry | Outbound | Package installation |
+| api.anthropic.com | Outbound | Claude API calls |
+| sentry.io | Outbound | Error reporting |
+| statsig.anthropic.com | Outbound | Feature flags |
+| VS Code marketplace | Outbound | Extension downloads |
+| **Everything else** | **BLOCKED** | Default-deny with REJECT |
+
+## Verification on startup
+
+The script verifies the firewall by:
+1. Confirming `https://example.com` is **blocked** (must fail — otherwise exit 1)
+2. Confirming `https://api.github.com` is **reachable** (warning only if it fails)
+
+All output is logged to `/tmp/firewall-init.log` for debugging.