Replace npm Claude Code with native binary installation

The Anthropic devcontainer feature installed Claude Code via npm as root,
making the package directory unwritable by the vscode user. This caused
the in-session auto-updater to fail with EACCES on every update attempt.

Replaces ghcr.io/anthropics/devcontainer-features/claude-code (npm) with
a new ./features/claude-code-native feature that uses Anthropic's official
native installer (https://claude.ai/install.sh). The native binary installs
to ~/.local/bin/claude owned by the container user, so claude update works
without permission issues.

Author: AnExiledDev

.devcontainer/CHANGELOG.md

@@ -12,6 +12,13 @@
 
 ### Changed
 
+#### Claude Code Installation
+- **Replaced npm installation with native binary** — swapped `ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5` (npm-based) for new `./features/claude-code-native` feature that installs via Anthropic's official native installer (`https://claude.ai/install.sh`)
+- **In-session auto-updater now works** — native binary installs to `~/.local/bin/claude` owned by the container user, so `claude update` can write freely without root permission issues
+- **setup-update-claude.sh** — stripped all npm fallback and `claude install` bootstrap code; now native-binary-only with 60s timeout and transitional npm cleanup
+- **setup-aliases.sh** — simplified `_CLAUDE_BIN` resolution to native binary path only (removed npm and `/usr/local/bin` fallbacks)
+- **setup.sh** — fixed background update script invocation to capture all output to log file instead of discarding via `&>/dev/null`
+
 #### System Prompt
 - **`<git_worktrees>` section** — Updated to document Claude Code native worktree convention (`<repo>/.claude/worktrees/`) as the recommended approach alongside the legacy `.worktrees/` convention. Added `EnterWorktree` tool guidance, `.worktreeinclude` file documentation, and path convention comparison table.
 

.devcontainer/CLAUDE.md

@@ -173,4 +173,4 @@ Labels are `custom-text` widgets with `merge: "no-padding"` so they fuse visuall
 
 ## Features
 
-Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1`.
+Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed as a native binary via `./features/claude-code-native` (uses Anthropic's official installer at `https://claude.ai/install.sh`).

.devcontainer/devcontainer.json

@@ -45,7 +45,7 @@
 	},
 
 	// Feature install order: external runtimes first (Node, uv, Rust, Bun),
-	// then Claude Code (needs Node), then custom features.
+	// then Claude Code native binary (no Node dependency), then custom features.
 	// 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.
@@ -57,7 +57,7 @@
 		"ghcr.io/devcontainers-extra/features/uv",
 		"ghcr.io/rails/devcontainer/features/bun",
 		"ghcr.io/devcontainers/features/rust",
-		"ghcr.io/anthropics/devcontainer-features/claude-code",
+		"./features/claude-code-native",
 		"./features/tmux",
 		"./features/agent-browser",
 		"./features/claude-monitor",
@@ -96,7 +96,7 @@
 		},
 		// 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/claude-code-native": {},
 		"./features/tmux": {},
 		"./features/ccusage": {
 			"version": "latest",

.devcontainer/features/claude-code-native/README.md

@@ -0,0 +1,47 @@
+# Claude Code CLI (Native Binary)
+
+Installs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as a native binary using Anthropic's official installer.
+
+Unlike the npm-based installation (`ghcr.io/anthropics/devcontainer-features/claude-code`), this feature installs the native binary directly to `~/.local/bin/claude`. The binary is owned by the container user, so the in-session auto-updater works without permission issues.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | `latest`, `stable`, or a specific semver (e.g., `2.1.52`). Set to `none` to skip. |
+| `username` | `automatic` | Container user to install for. `automatic` detects from `$_REMOTE_USER`. |
+
+## How it works
+
+1. Downloads the official installer from `https://claude.ai/install.sh`
+2. Runs it as the target user (not root)
+3. The installer handles platform detection, checksum verification, and binary placement
+4. Binary is installed to `~/.local/bin/claude` with versions stored in `~/.local/share/claude/versions/`
+
+## Usage
+
+```json
+{
+    "features": {
+        "./features/claude-code-native": {}
+    }
+}
+```
+
+With version pinning:
+
+```json
+{
+    "features": {
+        "./features/claude-code-native": {
+            "version": "2.1.52"
+        }
+    }
+}
+```
+
+## Why native over npm?
+
+The npm installation (`npm install -g @anthropic-ai/claude-code`) runs as root during the Docker build, creating a package owned by `root`. When the container user tries to auto-update Claude Code in-session, it fails with `EACCES` because it can't write to the root-owned package directory.
+
+The native binary installs to `~/.local/` under the container user's ownership, so `claude update` works without elevated permissions.

.devcontainer/features/claude-code-native/devcontainer-feature.json

@@ -0,0 +1,29 @@
+{
+	"id": "claude-code-native",
+	"version": "1.0.0",
+	"name": "Claude Code CLI (Native Binary)",
+	"description": "Installs Claude Code CLI as a native binary via the official Anthropic installer",
+	"documentationURL": "https://docs.anthropic.com/en/docs/claude-code",
+	"options": {
+		"version": {
+			"type": "string",
+			"description": "Version to install: 'latest', 'stable', or a specific semver. Use 'none' to skip.",
+			"default": "latest"
+		},
+		"username": {
+			"type": "string",
+			"description": "Container user to install for",
+			"default": "automatic"
+		}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"anthropic.claude-code"
+			]
+		}
+	},
+	"installsAfter": [
+		"ghcr.io/devcontainers/features/common-utils:2"
+	]
+}

.devcontainer/features/claude-code-native/install.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+set -euo pipefail
+
+VERSION="${VERSION:-latest}"
+USERNAME="${USERNAME:-automatic}"
+
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+	echo "[claude-code-native] Skipping installation (version=none)"
+	exit 0
+fi
+
+echo "[claude-code-native] Starting installation..."
+echo "[claude-code-native] Version: ${VERSION}"
+
+# === VALIDATE DEPENDENCIES ===
+if ! command -v curl &>/dev/null && ! command -v wget &>/dev/null; then
+	echo "[claude-code-native] ERROR: curl or wget is required"
+	echo "  Ensure common-utils feature is installed first"
+	exit 1
+fi
+
+# === DETECT USER ===
+if [ "${USERNAME}" = "auto" ] || [ "${USERNAME}" = "automatic" ]; then
+	if [ -n "${_REMOTE_USER:-}" ]; then
+		USERNAME="${_REMOTE_USER}"
+	elif getent passwd vscode >/dev/null 2>&1; then
+		USERNAME="vscode"
+	elif getent passwd node >/dev/null 2>&1; then
+		USERNAME="node"
+	elif getent passwd codespace >/dev/null 2>&1; then
+		USERNAME="codespace"
+	else
+		USERNAME="root"
+	fi
+fi
+
+USER_HOME=$(getent passwd "${USERNAME}" | cut -d: -f6)
+if [ -z "${USER_HOME}" ]; then
+	echo "[claude-code-native] ERROR: Could not determine home directory for ${USERNAME}"
+	exit 1
+fi
+
+echo "[claude-code-native] Installing for user: ${USERNAME} (home: ${USER_HOME})"
+
+# === PREPARE DIRECTORIES ===
+mkdir -p "${USER_HOME}/.local/bin"
+mkdir -p "${USER_HOME}/.local/share/claude"
+chown -R "${USERNAME}:" "${USER_HOME}/.local/bin" "${USER_HOME}/.local/share/claude"
+
+# === DETERMINE TARGET ===
+# The official installer accepts: stable, latest, or a specific semver
+TARGET=""
+if [ "${VERSION}" != "latest" ] && [ "${VERSION}" != "stable" ]; then
+	TARGET="${VERSION}"
+else
+	TARGET="${VERSION}"
+fi
+
+# === INSTALL ===
+# The official Anthropic installer handles:
+# - Platform detection (linux/darwin, x64/arm64, glibc/musl)
+# - Manifest download and checksum verification
+# - Binary download to ~/.local/bin/claude (symlink to ~/.local/share/claude/versions/*)
+echo "[claude-code-native] Downloading official installer..."
+
+if [ "${USERNAME}" = "root" ]; then
+	curl -fsSL https://claude.ai/install.sh | sh -s -- "${TARGET}"
+else
+	su - "${USERNAME}" -c "curl -fsSL https://claude.ai/install.sh | sh -s -- ${TARGET}"
+fi
+
+# === VERIFICATION ===
+CLAUDE_BIN="${USER_HOME}/.local/bin/claude"
+
+if [ -x "${CLAUDE_BIN}" ]; then
+	INSTALLED_VERSION=$(su - "${USERNAME}" -c "${CLAUDE_BIN} --version 2>/dev/null" || echo "unknown")
+	echo "[claude-code-native] ✓ Claude Code installed: ${INSTALLED_VERSION}"
+	echo "[claude-code-native]   Binary: ${CLAUDE_BIN}"
+else
+	echo "[claude-code-native] ERROR: Installation failed — ${CLAUDE_BIN} not found or not executable"
+	echo "[claude-code-native] Expected binary at: ${CLAUDE_BIN}"
+	ls -la "${USER_HOME}/.local/bin/" 2>/dev/null || true
+	exit 1
+fi
+
+echo "[claude-code-native] Installation complete"

.devcontainer/scripts/setup-aliases.sh

@@ -80,14 +80,8 @@ if [ "\$TERM" = "xterm" ] || [ -z "\$TERM" ]; then
 fi
 export COLORTERM="\${COLORTERM:-truecolor}"
 
-# Prefer native binary over npm-installed version
-if [ -x "\$HOME/.local/bin/claude" ]; then
-    _CLAUDE_BIN="\$HOME/.local/bin/claude"
-elif [ -x /usr/local/bin/claude ]; then
-    _CLAUDE_BIN=/usr/local/bin/claude
-else
-    _CLAUDE_BIN=claude
-fi
+# Native binary (installed by claude-code-native feature)
+_CLAUDE_BIN="\$HOME/.local/bin/claude"
 
 # ChromaTerm wrapper (if ct is installed, wrap claude through it)
 if command -v ct >/dev/null 2>&1; then

.devcontainer/scripts/setup-update-claude.sh

@@ -25,52 +25,43 @@ fi
 
 # === CLEANUP TRAP ===
 cleanup() {
-	rm -f "${_TMPDIR}/claude-update" 2>/dev/null || true
-	rm -f "${_TMPDIR}/claude-update-manifest.json" 2>/dev/null || true
 	rm -rf "$LOCK_FILE" 2>/dev/null || true
 }
 trap cleanup EXIT
 
-# === VERIFY CLAUDE IS INSTALLED ===
-if ! command -v claude &>/dev/null; then
-	log "Claude Code not found, skipping update"
-	exit 0
-fi
+# === NATIVE BINARY ===
+NATIVE_BIN="$HOME/.local/bin/claude"
 
-# === ENSURE NATIVE BINARY EXISTS ===
-# 'claude install' puts the binary at ~/.local/bin/claude (symlink to ~/.local/share/claude/versions/*)
-# Legacy manual installs used /usr/local/bin/claude — check both, prefer ~/.local
-if [ -x "$HOME/.local/bin/claude" ]; then
-	NATIVE_BIN="$HOME/.local/bin/claude"
-elif [ -x "/usr/local/bin/claude" ]; then
-	NATIVE_BIN="/usr/local/bin/claude"
-else
-	NATIVE_BIN=""
+if [ ! -x "$NATIVE_BIN" ]; then
+	log "ERROR: Native binary not found at ${NATIVE_BIN}"
+	log "  The claude-code-native feature should install this during container build."
+	log "  Try rebuilding the container or running: curl -fsSL https://claude.ai/install.sh | sh"
+	exit 1
 fi
-if [ -z "$NATIVE_BIN" ]; then
-	log "Native binary not found, installing..."
-	if claude install 2>&1 | tee -a "$LOG_FILE"; then
-		log "Native binary installed successfully"
+
+# === TRANSITIONAL: Remove leftover npm installation ===
+NPM_CLAUDE="$(npm config get prefix 2>/dev/null)/lib/node_modules/@anthropic-ai/claude-code"
+if [ -d "$NPM_CLAUDE" ]; then
+	log "Removing leftover npm installation at ${NPM_CLAUDE}..."
+	if sudo npm uninstall -g @anthropic-ai/claude-code 2>/dev/null; then
+		log "Removed leftover npm installation"
 	else
-		log "WARNING: 'claude install' failed, skipping"
-		exit 0
+		log "WARNING: Could not remove npm installation (non-blocking)"
 	fi
-	# Skip update check on first install — next start will handle it
-	exit 0
 fi
 
 # === CHECK FOR UPDATES ===
 CURRENT_VERSION=$("$NATIVE_BIN" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")
 log "Current version: ${CURRENT_VERSION}"
 
-# Use the official update command (handles download, verification, and versioned install)
-if "$NATIVE_BIN" update 2>&1 | tee -a "$LOG_FILE"; then
+# Use the official update command with timeout (handles download, verification, and versioned install)
+if timeout 60 "$NATIVE_BIN" update 2>&1 | tee -a "$LOG_FILE"; then
 	UPDATED_VERSION=$("$NATIVE_BIN" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")
 	if [ "$CURRENT_VERSION" != "$UPDATED_VERSION" ]; then
 		log "Updated Claude Code: ${CURRENT_VERSION} → ${UPDATED_VERSION}"
 	else
 		log "Already up to date (${CURRENT_VERSION})"
 	fi
 else
-	log "WARNING: 'claude update' failed, skipping"
+	log "WARNING: 'claude update' failed or timed out"
 fi

.devcontainer/scripts/setup.sh

@@ -118,7 +118,7 @@ run_script "$SCRIPT_DIR/setup-terminal.sh" "$SETUP_TERMINAL"
 
 # Background the update to avoid blocking container start
 if [ "$SETUP_UPDATE_CLAUDE" = "true" ] && [ -f "$SCRIPT_DIR/setup-update-claude.sh" ]; then
-    bash "$SCRIPT_DIR/setup-update-claude.sh" &>/dev/null &
+    bash "$SCRIPT_DIR/setup-update-claude.sh" >>"${TMPDIR:-/tmp}/claude-update.log" 2>&1 &
     disown
     SETUP_RESULTS+=("setup-update-claude:background")
 else