codeforge-dev 1.11.0 → 1.13.0

package/.devcontainer/devcontainer.json

@@ -9,13 +9,31 @@
 		"WORKSPACE_ROOT": "/workspaces",
 		"CLAUDE_CONFIG_DIR": "/workspaces/.claude",
 		"GH_CONFIG_DIR": "/workspaces/.gh",
-		"TMPDIR": "/workspaces/.tmp"
+		"TMPDIR": "/workspaces/.tmp",
+		"CLAUDECODE": null
+	},
+
+	"secrets": {
+		"GH_TOKEN": {
+			"description": "GitHub Personal Access Token (optional - for git auth)",
+			"documentationUrl": "https://github.com/settings/tokens"
+		},
+		"NPM_TOKEN": {
+			"description": "NPM auth token (optional - for npm registry)",
+			"documentationUrl": "https://www.npmjs.com/settings/~/tokens"
+		},
+		"GH_USERNAME": {
+			"description": "GitHub username for git config (optional)"
+		},
+		"GH_EMAIL": {
+			"description": "GitHub email for git config (optional)"
+		}
 	},
 
 	// Feature install order: external runtimes first (Node, uv, Rust, Bun),
 	// then Claude Code (needs Node), then custom features.
-	// npm-dependent features (agent-browser, ccusage, ccburn, biome, lsp-servers)
-	// must come after Node. uv-dependent features (ruff, claude-monitor) must
+	// npm-dependent features (agent-browser, ccusage, ccburn, claude-session-dashboard,
+	// biome, lsp-servers) must come after Node. uv-dependent features (ruff, claude-monitor) must
 	// come after uv. cargo-dependent features (ccms) must come after Rust.
 	// notify-hook is last (lightweight, no dependencies).
 	"overrideFeatureInstallOrder": [
@@ -33,6 +51,7 @@
 		"./features/ccburn",
 		"./features/ccstatusline",
 		"./features/ccms",
+		"./features/claude-session-dashboard",
 		"./features/ast-grep",
 		"./features/tree-sitter",
 		"./features/lsp-servers",
@@ -46,20 +65,22 @@
 	],
 
 	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
+		"ghcr.io/devcontainers/features/node:1.7.1": {
 			"version": "lts",
 			"nodeGypDependencies": true
 		},
-		"ghcr.io/devcontainers/features/github-cli:1": {},
-		"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+		"ghcr.io/devcontainers/features/github-cli:1.1.0": {},
+		"ghcr.io/devcontainers/features/docker-outside-of-docker:1.6": {
 			"moby": false
 		},
-		"ghcr.io/devcontainers-extra/features/uv:1": {},
+		"ghcr.io/devcontainers-extra/features/uv:1.0": {},
 		"ghcr.io/rails/devcontainer/features/bun:1.0.2": {},
-		"ghcr.io/devcontainers/features/rust:1": {
+		"ghcr.io/devcontainers/features/rust:1.5.0": {
 			"version": "latest"
 		},
-		"ghcr.io/anthropics/devcontainer-features/claude-code:1": {},
+		// Uncomment to add Go runtime (not installed by default):
+		// "ghcr.io/devcontainers/features/go:1": {},
+		"ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5": {},
 		"./features/tmux": {},
 		"./features/ccusage": {
 			"version": "latest",
@@ -80,6 +101,12 @@
 			"username": "automatic"
 		},
 		"./features/ccms": {},
+		"./features/claude-session-dashboard": {
+			"version": "latest",
+			"port": "3000",
+			"shells": "both",
+			"username": "automatic"
+		},
 		"./features/ast-grep": {},
 		"./features/tree-sitter": {},
 		"./features/lsp-servers": {},
@@ -111,18 +138,21 @@
 		"vscode": {
 			"settings": {
 				"terminal.integrated.profiles.linux": {
+					"zsh": {
+						"path": "zsh"
+					},
 					"bash": {
 						"path": "bash"
 					},
 					"Claude Teams (tmux)": {
-						"path": "bash",
+						"path": "zsh",
 						"args": [
 							"-c",
 							"if tmux has-session -t claude-teams 2>/dev/null; then exec tmux -u new-session -t claude-teams; else exec tmux -u new-session -s claude-teams; fi"
 						]
 					}
 				},
-				"terminal.integrated.defaultProfile.linux": "bash",
+				"terminal.integrated.defaultProfile.linux": "zsh",
 				"terminal.integrated.enableBell": true,
 				"terminal.integrated.commandsToSkipShell": [
 					"-workbench.action.quickOpen",

package/.devcontainer/docs/configuration-reference.md

@@ -30,7 +30,9 @@ These control what `setup.sh` does on each container start. Copy `.env.example`
 | `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file |
 | `SETUP_PLUGINS` | `true` | Install Anthropic plugins + register local marketplace |
 | `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary |
+| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal |
 | `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` |
 | `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation |
 
 ## `devcontainer.json` `remoteEnv` (Container Runtime)
@@ -43,6 +45,7 @@ These environment variables are set in every terminal session inside the contain
 | `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
 | `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory |
 | `TMPDIR` | `/workspaces/.tmp` | Temporary files directory |
+| `CLAUDECODE` | `null` (unset) | Unsets the variable to allow nested Claude Code sessions (claude-in-claude) |
 
 ## `config/file-manifest.json` (File Copy Rules)
 

package/.devcontainer/docs/plugins.md

@@ -16,7 +16,8 @@ plugins/devs-marketplace/
     ├── protected-files-guard/ # Safety: protect sensitive files
     ├── auto-formatter/        # Batch formatter (Stop hook)
     ├── auto-linter/           # Batch linter (Stop hook)
-    └── code-directive/        # Agents, skills, hooks
+    ├── code-directive/        # Agents, skills, hooks
+    └── workspace-scope-guard/ # Workspace scope enforcement
 ```
 
 Each plugin has a `.claude-plugin/plugin.json` manifest defining its name, description, and capabilities.
@@ -146,9 +147,15 @@ Runs as a PreToolUse hook on Write and Edit operations.
 
 **Components**:
 - **17 custom agents** — Specialized agent definitions for different task types (architect, test-writer, refactorer, etc.)
-- **16 coding skills** — Domain-specific reference materials (FastAPI, Docker, testing patterns, etc.)
+- **28 coding skills** — Domain-specific reference materials (FastAPI, Docker, testing patterns, spec workflow, etc.)
 - **Agent redirection hook** — Transparently swaps built-in agent types to custom agents (e.g., `Explore` → `explorer`, `Plan` → `architect`)
 - **Syntax validation hook** — Validates code syntax before commits
 - **Skill auto-suggestion hook** — Suggests relevant skills based on conversation context
 
 For detailed agent and skill documentation, see the agent markdown files in `plugins/devs-marketplace/plugins/code-directive/agents/` and skill files in `plugins/devs-marketplace/plugins/code-directive/skills/`.
+
+### workspace-scope-guard
+
+**Purpose**: Enforces workspace scope by blocking writes outside the working directory and warning on out-of-scope reads.
+
+Runs as a PreToolUse hook on Write, Edit, and Read operations. Compares file paths against the current working directory and rejects modifications to files outside the project scope. Read operations outside scope produce a warning but are not blocked. Resolves symlinks and worktree paths correctly via `os.path.realpath()`.

package/.devcontainer/docs/troubleshooting.md

@@ -6,7 +6,7 @@ Common issues and solutions for the CodeForge devcontainer.
 
 **Problem**: Container fails to build during feature installation.
 
-- Check Docker has sufficient memory (4GB+ recommended). CodeForge sets `--memory=4g` by default.
+- Check Docker has sufficient memory (6GB+ recommended). CodeForge sets `--memory=6g` by default.
 - If a specific feature fails, disable it temporarily by setting `"version": "none"` in `devcontainer.json`.
 - Check internet connectivity — most features download binaries from GitHub releases.
 - If hitting GitHub API rate limits during build, set `GH_TOKEN` or `GITHUB_TOKEN` as an environment variable.
@@ -107,7 +107,7 @@ Common issues and solutions for the CodeForge devcontainer.
 
 **Problem**: Container is slow or running out of memory.
 
-- CodeForge defaults to 4GB RAM / 8GB swap. Increase in `devcontainer.json` `runArgs`.
+- CodeForge defaults to 6GB RAM / 12GB swap. Increase in `devcontainer.json` `runArgs`.
 - Disable features you don't need with `"version": "none"`.
 - The background Claude Code update runs once on startup — it's not persistent.
 

package/.devcontainer/features/README.md

@@ -10,16 +10,20 @@ This directory contains DevContainer Features for AI coding agent environments.
 | `agent-browser` | Headless browser automation for AI agents | ✅ |
 | `claude-monitor` | Real-time token usage monitoring | ✅ |
 | `ccusage` | Token usage analytics CLI | ✅ |
-| `ccburn` | Visual token burn rate tracker with pace indicators | ✅ New |
+| `ccburn` | Visual token burn rate tracker with pace indicators | ✅ |
 | `ccstatusline` | 6-line powerline status display (v1.1.0) | ✅ |
 | `ast-grep` | Structural code search using AST patterns | ✅ |
 | `tree-sitter` | Parser with JS/TS/Python grammars | ✅ |
 | `lsp-servers` | Pyright and TypeScript language servers | ✅ |
 | `biome` | Fast JS/TS/JSON/CSS formatter | ✅ |
+| `ruff` | Fast Python linter and formatter | ✅ |
+| `shfmt` | Shell script formatter | ✅ (disabled by default) |
+| `shellcheck` | Static analysis for shell scripts | ✅ (disabled by default) |
+| `hadolint` | Dockerfile linter | ✅ (disabled by default) |
+| `dprint` | Pluggable formatter for Markdown/YAML/TOML | ✅ (disabled by default) |
+| `ccms` | Claude Code session history search | ✅ |
 | `notify-hook` | Desktop notifications on Claude completion | ✅ |
-| `splitrail` | Git worktree management for parallel branches | ✅ |
 | `mcp-qdrant` | Qdrant vector database MCP server | ✅ (optional) |
-| `mcp-reasoner` | Enhanced AI reasoning MCP server | ✅ (optional) |
 | `claude-code` | Fallback config for Anthropic's official Claude Code feature | ✅ (config only) |
 
 > **Note**: Claude Code itself is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1` (Anthropic's official feature). The local `claude-code/` directory provides only fallback configuration.
@@ -99,16 +103,11 @@ ghcr.io/yourorg/codeforge-features/feature-name:1
 
 ## Migration from Modules
 
-CodeForge modules are being converted to DevContainer Features:
+CodeForge modules have been converted to DevContainer Features:
 
 | Old Module | New Feature | Status |
 |-----------|-------------|---------|
 | mcp_qdrant | mcp-qdrant | ✅ Complete |
-| mcp_reasoner | mcp-reasoner | ✅ Complete |
-| mcp_browser | mcp-browser | 🔜 Planned |
-| mcp_sourcerer | mcp-sourcerer | 🔜 Planned |
-| mcp_obsidian | mcp-obsidian | 🔜 Planned |
-| mcp_code_runner | mcp-code-runner | 🔜 Planned |
 
 ## Resources
 

package/.devcontainer/features/agent-browser/devcontainer-feature.json

@@ -1,23 +1,23 @@
 {
-  "id": "agent-browser",
-  "version": "1.0.0",
-  "name": "agent-browser",
-  "description": "Headless browser automation CLI for AI agents (Vercel Labs)",
-  "documentationURL": "https://github.com/vercel-labs/agent-browser",
-  "options": {
-    "version": {
-      "type": "string",
-      "description": "agent-browser npm package version",
-      "default": "latest"
-    },
-    "username": {
-      "type": "string",
-      "description": "Container user to install for",
-      "default": "automatic"
-    }
-  },
-  "installsAfter": [
-    "ghcr.io/devcontainers/features/common-utils:2",
-    "ghcr.io/devcontainers/features/node:1"
-  ]
+	"id": "agent-browser",
+	"version": "1.0.0",
+	"name": "agent-browser",
+	"description": "Headless browser automation CLI for AI agents (Vercel Labs)",
+	"documentationURL": "https://github.com/vercel-labs/agent-browser",
+	"options": {
+		"version": {
+			"type": "string",
+			"description": "agent-browser npm package version",
+			"default": "0.11.1"
+		},
+		"username": {
+			"type": "string",
+			"description": "Container user to install for",
+			"default": "automatic"
+		}
+	},
+	"installsAfter": [
+		"ghcr.io/devcontainers/features/common-utils:2",
+		"ghcr.io/devcontainers/features/node:1"
+	]
 }

package/.devcontainer/features/agent-browser/install.sh

@@ -64,13 +64,6 @@ agent-browser install --with-deps 2>/dev/null || {
     agent-browser install 2>/dev/null || true
 }
 
-# Install Playwright Chromium only (not all browsers)
-echo "[agent-browser] Installing Playwright Chromium..."
-npx playwright install chromium --with-deps 2>/dev/null || {
-    echo "[agent-browser] WARNING: Playwright chromium install with deps failed, trying without --with-deps"
-    npx playwright install chromium 2>/dev/null || true
-}
-
 echo "[agent-browser] Installed: $(agent-browser --version 2>/dev/null || echo 'unknown')"
 echo "[agent-browser] Installation complete"
 echo ""

package/.devcontainer/features/ast-grep/devcontainer-feature.json

@@ -1,24 +1,24 @@
 {
-  "id": "ast-grep",
-  "version": "1.0.0",
-  "name": "ast-grep",
-  "description": "Installs ast-grep CLI for structural code search, lint, and rewriting using AST matching",
-  "maintainer": "AnExiledDev",
-  "documentationURL": "https://ast-grep.github.io/",
-  "options": {
-    "version": {
-      "type": "string",
-      "description": "@ast-grep/cli npm package version (e.g., 'latest', '0.31.1')",
-      "default": "latest"
-    },
-    "username": {
-      "type": "string",
-      "description": "Container user to install for",
-      "default": "automatic"
-    }
-  },
-  "installsAfter": [
-    "ghcr.io/devcontainers/features/common-utils:2",
-    "ghcr.io/devcontainers/features/node:1"
-  ]
+	"id": "ast-grep",
+	"version": "1.0.0",
+	"name": "ast-grep",
+	"description": "Installs ast-grep CLI for structural code search, lint, and rewriting using AST matching",
+	"maintainer": "AnExiledDev",
+	"documentationURL": "https://ast-grep.github.io/",
+	"options": {
+		"version": {
+			"type": "string",
+			"description": "@ast-grep/cli npm package version (e.g., 'latest', '0.31.1')",
+			"default": "0.40.5"
+		},
+		"username": {
+			"type": "string",
+			"description": "Container user to install for",
+			"default": "automatic"
+		}
+	},
+	"installsAfter": [
+		"ghcr.io/devcontainers/features/common-utils:2",
+		"ghcr.io/devcontainers/features/node:1"
+	]
 }

package/.devcontainer/features/biome/devcontainer-feature.json

@@ -1,16 +1,14 @@
 {
-  "id": "biome",
-  "version": "1.0.0",
-  "name": "Biome",
-  "description": "Fast JS/TS/JSON/CSS formatter and linter",
-  "options": {
-    "version": {
-      "type": "string",
-      "default": "latest",
-      "description": "Biome version to install"
-    }
-  },
-  "installsAfter": [
-    "ghcr.io/devcontainers/features/node"
-  ]
+	"id": "biome",
+	"version": "1.0.0",
+	"name": "Biome",
+	"description": "Fast JS/TS/JSON/CSS formatter and linter",
+	"options": {
+		"version": {
+			"type": "string",
+			"default": "2.4.2",
+			"description": "Biome version to install"
+		}
+	},
+	"installsAfter": ["ghcr.io/devcontainers/features/node"]
 }

package/.devcontainer/features/ccms/install.sh

@@ -52,24 +52,41 @@ fi
 
 echo "[ccms] Installing for user: ${USERNAME}"
 
+# === BUILD CACHE ===
+CACHE_DIR="/workspaces/.devcontainer/.build-cache/bin"
+
 # === INSTALL ===
 REPO_URL="https://github.com/mkusaka/ccms"
 
-if [ "${CCMS_VERSION}" = "latest" ]; then
-    echo "[ccms] Building from main branch..."
-    cargo install --git "${REPO_URL}" 2>&1 | tail -5
+if [ -x "${CACHE_DIR}/ccms" ]; then
+    echo "[ccms] Using cached binary from ${CACHE_DIR}/ccms"
+    cp "${CACHE_DIR}/ccms" /usr/local/bin/ccms
+    chmod +x /usr/local/bin/ccms
 else
-    echo "[ccms] Building from ref: ${CCMS_VERSION}..."
-    cargo install --git "${REPO_URL}" --rev "${CCMS_VERSION}" 2>&1 | tail -5
-fi
+    if [ "${CCMS_VERSION}" = "latest" ]; then
+        echo "[ccms] Building from main branch..."
+        cargo install --git "${REPO_URL}" --rev f90d259a4476 2>&1 | tail -5
+    else
+        echo "[ccms] Building from ref: ${CCMS_VERSION}..."
+        cargo install --git "${REPO_URL}" --rev "${CCMS_VERSION}" 2>&1 | tail -5
+    fi
+
+    # === ENSURE BINARY IS ON PATH ===
+    # cargo install puts binaries in $CARGO_HOME/bin or ~/.cargo/bin
+    # Symlink to /usr/local/bin so it's available to all users
+    CARGO_BIN="${CARGO_HOME:-$HOME/.cargo}/bin/ccms"
+    if [ -f "${CARGO_BIN}" ] && [ ! -f /usr/local/bin/ccms ]; then
+        ln -s "${CARGO_BIN}" /usr/local/bin/ccms
+        echo "[ccms] Symlinked ${CARGO_BIN} → /usr/local/bin/ccms"
+    fi
 
-# === ENSURE BINARY IS ON PATH ===
-# cargo install puts binaries in $CARGO_HOME/bin or ~/.cargo/bin
-# Symlink to /usr/local/bin so it's available to all users
-CARGO_BIN="${CARGO_HOME:-$HOME/.cargo}/bin/ccms"
-if [ -f "${CARGO_BIN}" ] && [ ! -f /usr/local/bin/ccms ]; then
-    ln -s "${CARGO_BIN}" /usr/local/bin/ccms
-    echo "[ccms] Symlinked ${CARGO_BIN} → /usr/local/bin/ccms"
+    # Cache the binary for future rebuilds
+    mkdir -p "${CACHE_DIR}"
+    CARGO_BIN="${CARGO_HOME:-$HOME/.cargo}/bin/ccms"
+    if [ -f "${CARGO_BIN}" ]; then
+        cp "${CARGO_BIN}" "${CACHE_DIR}/ccms"
+        echo "[ccms] Cached binary to ${CACHE_DIR}/ccms"
+    fi
 fi
 
 # === VERIFICATION ===

package/.devcontainer/features/claude-session-dashboard/README.md

@@ -0,0 +1,40 @@
+# Claude Session Dashboard (devcontainer feature)
+
+Installs [claude-session-dashboard](https://github.com/dlupiak/claude-session-dashboard) — a local analytics dashboard for Claude Code sessions.
+
+## What it provides
+
+- `claude-dashboard` command to launch the web UI
+- Session browsing with full-text search and filtering
+- Token usage breakdown, cost estimates, and activity heatmaps
+- Tool call timeline visualization
+- Per-project aggregated analytics
+- Settings persisted across container rebuilds via symlink to `/workspaces/.claude-dashboard/`
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | npm package version (`latest`, `1.0.0`, or `none` to skip) |
+| `port` | `3000` | Default port for the dashboard server |
+| `shells` | `both` | Shell configs to add alias to (`bash`, `zsh`, `both`) |
+| `username` | `automatic` | Container user to install for |
+
+## Usage
+
+```bash
+# Start the dashboard (default port 3000)
+claude-dashboard
+
+# Start on a custom port
+claude-dashboard -p 8080
+
+# Show help
+claude-dashboard --help
+```
+
+The dashboard reads session data from `~/.claude/projects/` (symlinked to `/workspaces/.claude/projects/` in this devcontainer).
+
+## How persistence works
+
+Dashboard settings and cache are stored at `~/.claude-dashboard/`. Since the home directory is ephemeral in devcontainers, a poststart hook symlinks `~/.claude-dashboard` → `/workspaces/.claude-dashboard/`, which is bind-mounted and survives rebuilds.

package/.devcontainer/features/claude-session-dashboard/devcontainer-feature.json

@@ -0,0 +1,35 @@
+{
+  "id": "claude-session-dashboard",
+  "version": "1.0.0",
+  "name": "Claude Session Dashboard",
+  "description": "Local analytics dashboard for Claude Code sessions (token usage, tool calls, cost estimates)",
+  "maintainer": "AnExiledDev",
+  "documentationURL": "https://github.com/dlupiak/claude-session-dashboard",
+  "options": {
+    "version": {
+      "type": "string",
+      "description": "Dashboard version (e.g., 'latest', '1.0.0', 'none' to skip)",
+      "default": "latest"
+    },
+    "port": {
+      "type": "string",
+      "description": "Default port for the dashboard server",
+      "default": "3000"
+    },
+    "shells": {
+      "type": "string",
+      "description": "Which shells to configure aliases in (bash, zsh, or both)",
+      "default": "both",
+      "enum": ["bash", "zsh", "both"],
+      "proposals": ["bash", "zsh", "both"]
+    },
+    "username": {
+      "type": "string",
+      "description": "Container user to install for",
+      "default": "automatic"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/node:1"
+  ]
+}

package/.devcontainer/features/claude-session-dashboard/install.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+set -euo pipefail
+
+# ==============================
+# Claude Session Dashboard
+# DevContainer Feature Installer
+# ==============================
+
+# === IMPORT OPTIONS ===
+DASHBOARD_VERSION="${VERSION:-latest}"
+PORT="${PORT:-3000}"
+SHELLS="${SHELLS:-both}"
+USERNAME="${USERNAME:-automatic}"
+
+# === SKIP IF DISABLED ===
+if [ "${DASHBOARD_VERSION}" = "none" ]; then
+    echo "[claude-session-dashboard] Skipping installation (version=none)"
+    exit 0
+fi
+
+echo "[claude-session-dashboard] Starting installation..."
+
+# === SOURCE NVM ===
+if [ -f /usr/local/share/nvm/nvm.sh ]; then
+    source /usr/local/share/nvm/nvm.sh
+fi
+
+# === VALIDATE DEPENDENCIES ===
+if ! command -v npm &>/dev/null; then
+    echo "[claude-session-dashboard] ERROR: npm is not available"
+    echo "  Ensure the node feature is installed first"
+    exit 1
+fi
+
+NODE_MAJOR="$(node --version 2>/dev/null | sed 's/v\([0-9]*\).*/\1/' || echo 0)"
+if [ "${NODE_MAJOR}" -lt 18 ]; then
+    echo "[claude-session-dashboard] ERROR: Node.js >= 18 required (found v${NODE_MAJOR})"
+    exit 1
+fi
+
+# === VALIDATE INPUT ===
+if [[ ! "${SHELLS}" =~ ^(bash|zsh|both)$ ]]; then
+    echo "[claude-session-dashboard] ERROR: shells must be 'bash', 'zsh', or 'both'"
+    exit 1
+fi
+
+if [[ ! "${DASHBOARD_VERSION}" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+    echo "[claude-session-dashboard] ERROR: version contains invalid characters"
+    exit 1
+fi
+
+# === DETECT USER ===
+if [ "${USERNAME}" = "auto" ] || [ "${USERNAME}" = "automatic" ]; then
+    USERNAME=""
+    for CURRENT_USER in vscode node codespace; do
+        if id -u "${CURRENT_USER}" >/dev/null 2>&1; then
+            USERNAME=${CURRENT_USER}
+            break
+        fi
+    done
+    [ -z "${USERNAME}" ] && USERNAME=root
+elif [ "${USERNAME}" = "none" ] || ! id -u "${USERNAME}" >/dev/null 2>&1; then
+    USERNAME=root
+fi
+
+USER_HOME=$(eval echo "~${USERNAME}")
+if [ ! -d "${USER_HOME}" ]; then
+    echo "[claude-session-dashboard] ERROR: Home directory not found for user ${USERNAME}"
+    exit 1
+fi
+
+echo "[claude-session-dashboard] Installing for user: ${USERNAME}"
+
+# === INSTALL VIA NPM ===
+echo "[claude-session-dashboard] Installing claude-session-dashboard@${DASHBOARD_VERSION} globally..."
+npm install -g "claude-session-dashboard@${DASHBOARD_VERSION}"
+
+# === PERSISTENCE SYMLINK (POSTSTART HOOK) ===
+# Settings/cache live at ~/.claude-dashboard, which is ephemeral (/home/vscode).
+# Create a poststart hook to symlink it to /workspaces/.claude-dashboard for persistence.
+POSTSTART_DIR="/usr/local/devcontainer-poststart.d"
+HOOK_SCRIPT="${POSTSTART_DIR}/claude-dashboard-symlink.sh"
+
+mkdir -p "${POSTSTART_DIR}"
+cat > "${HOOK_SCRIPT}" << 'HOOKEOF'
+#!/bin/bash
+# Symlink ~/.claude-dashboard → /workspaces/.claude-dashboard for persistence
+DASHBOARD_DATA="/workspaces/.claude-dashboard"
+USER_HOME="${HOME:-/home/vscode}"
+LINK_PATH="${USER_HOME}/.claude-dashboard"
+
+mkdir -p "${DASHBOARD_DATA}"
+
+# Already correct symlink — nothing to do
+if [ -L "${LINK_PATH}" ]; then
+    CURRENT_TARGET="$(readlink "${LINK_PATH}")"
+    if [ "${CURRENT_TARGET}" = "${DASHBOARD_DATA}" ]; then
+        exit 0
+    fi
+    rm "${LINK_PATH}"
+fi
+
+# Real directory exists — merge contents, then replace with symlink
+if [ -d "${LINK_PATH}" ]; then
+    cp -rn "${LINK_PATH}/." "${DASHBOARD_DATA}/" 2>/dev/null || true
+    rm -rf "${LINK_PATH}"
+fi
+
+ln -s "${DASHBOARD_DATA}" "${LINK_PATH}"
+HOOKEOF
+chmod +x "${HOOK_SCRIPT}"
+echo "[claude-session-dashboard] Created poststart hook for settings persistence"
+
+# === SHELL ALIASES ===
+ALIAS_CMD="alias claude-dashboard=\"claude-dashboard --port ${PORT}\""
+
+configure_shell() {
+    local shell_rc="$1"
+    local shell_name="$2"
+
+    if [ ! -f "${shell_rc}" ]; then
+        echo "[claude-session-dashboard] Creating ${shell_name} config: ${shell_rc}"
+        sudo -u "${USERNAME}" touch "${shell_rc}"
+    fi
+
+    if grep -q "alias claude-dashboard=" "${shell_rc}"; then
+        echo "[claude-session-dashboard] ${shell_name} alias already configured. Skipping..."
+    else
+        echo "[claude-session-dashboard] Adding alias to ${shell_name}"
+        echo "${ALIAS_CMD}" >> "${shell_rc}"
+        chown "${USERNAME}:${USERNAME}" "${shell_rc}" 2>/dev/null || true
+    fi
+}
+
+if [ "${SHELLS}" = "bash" ] || [ "${SHELLS}" = "both" ]; then
+    configure_shell "${USER_HOME}/.bashrc" "bash"
+fi
+
+if [ "${SHELLS}" = "zsh" ] || [ "${SHELLS}" = "both" ]; then
+    configure_shell "${USER_HOME}/.zshrc" "zsh"
+fi
+
+# === VERIFICATION ===
+echo "[claude-session-dashboard] Verifying installation..."
+if command -v claude-dashboard &>/dev/null; then
+    INSTALLED_VERSION="$(claude-dashboard --version 2>/dev/null || echo "unknown")"
+    echo "[claude-session-dashboard] ✓ claude-dashboard installed (${INSTALLED_VERSION})"
+else
+    echo "[claude-session-dashboard] WARNING: claude-dashboard not found in PATH"
+    echo "  The global npm install may need PATH adjustment"
+    echo "  Try: npx claude-session-dashboard --version"
+fi
+
+# === SUMMARY ===
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Claude Session Dashboard Installation Complete"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Configuration:"
+echo "  • User: ${USERNAME}"
+echo "  • Version: ${DASHBOARD_VERSION}"
+echo "  • Default port: ${PORT}"
+echo "  • Shells: ${SHELLS}"
+echo "  • Settings persist to: /workspaces/.claude-dashboard/"
+echo ""
+echo "Usage:"
+echo "  claude-dashboard           # Start on port ${PORT}"
+echo "  claude-dashboard -p 8080   # Start on custom port"
+echo "  claude-dashboard --help    # Full options"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"