codeforge-dev 1.14.1 → 2.0.0

package/.devcontainer/README.md

@@ -1,6 +1,6 @@
 # CodeForge Usage Guide
 
-Everything you need to know once you're inside the devcontainer.
+Everything you need to know once you're inside the devcontainer. These instructions apply regardless of which client you used to start the container — VS Code, the `devcontainer` CLI, JetBrains Gateway, DevPod, or GitHub Codespaces.
 
 ## Quick Start
 
@@ -40,7 +40,20 @@ Get an API key from [console.anthropic.com](https://console.anthropic.com/).
 
 ### Credential Persistence
 
-Authentication credentials are stored in `/workspaces/.claude/` and persist across container rebuilds.
+Authentication credentials are stored in `~/.claude/` and persist across container rebuilds via a Docker named volume.
+
+### Long-Lived Token Authentication
+
+For headless or automated environments, you can use a long-lived auth token instead of browser login:
+
+1. Generate a token: `claude setup-token`
+2. Add to `.devcontainer/.secrets`:
+   ```bash
+   CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here
+   ```
+3. On next container start, `setup-auth.sh` will create `~/.claude/.credentials.json` automatically.
+
+You can also set `CLAUDE_AUTH_TOKEN` as a Codespaces secret for cloud environments.
 
 For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
 
@@ -111,7 +124,7 @@ Expected output shows your authenticated account and token scopes.
 
 ### Credential Persistence
 
-GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace.
+GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace. Claude Code credentials persist via a Docker named volume mounted at `~/.claude/`.
 
 **You only need to authenticate once.** After running `gh auth login` or configuring `.secrets`, your credentials will survive container rebuilds and be available in future sessions.
 
@@ -119,7 +132,7 @@ GitHub CLI credentials are automatically persisted across container rebuilds. Th
 
 ### The `cc` Command
 
-The `cc` command is an alias that launches Claude Code with the project's system prompt and plan-mode permissions. For Agent Teams split-pane support, use the **"Claude Teams (tmux)"** terminal profile in VS Code (dropdown next to the `+` button) or connect via `connect-external-terminal.sh`.
+The `cc` command is an alias that launches Claude Code with the project's system prompt and plan-mode permissions. For Agent Teams split-pane support, use the **"Claude Teams (tmux)"** terminal profile in VS Code (dropdown next to the `+` button) or connect via `.codeforge/scripts/connect-external-terminal.sh`.
 
 ```bash
 cc                    # Start Claude Code in current directory
@@ -199,7 +212,7 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude configuration directory |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Claude configuration directory |
 | `SETUP_CONFIG` | `true` | Copy config files during setup (per `file-manifest.json`) |
 | `SETUP_ALIASES` | `true` | Add `cc`/`claude`/`ccraw` aliases to shell |
 | `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` |
@@ -212,7 +225,7 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 
 ### Claude Code Settings
 
-Default settings are in `.devcontainer/config/defaults/settings.json`. File copying is controlled by `config/file-manifest.json`, which specifies per-file overwrite behavior (`"if-changed"`, `"always"`, or `"never"`).
+Default settings are in `.codeforge/config/settings.json`. File copying is controlled by `.codeforge/file-manifest.json`, which specifies per-file overwrite behavior (`"if-changed"`, `"always"`, or `"never"`).
 
 To add a custom config file, append an entry to `file-manifest.json`:
 ```json
@@ -230,7 +243,7 @@ Key defaults:
 
 ### Keybindings
 
-Default keybindings are in `.devcontainer/config/defaults/keybindings.json` (empty by default — Claude Code defaults apply). Customize by adding entries to the `bindings` array.
+Default keybindings are in `.codeforge/config/keybindings.json` (empty by default — Claude Code defaults apply). Customize by adding entries to the `bindings` array.
 
 **VS Code Terminal Passthrough**: `Ctrl+P` and `Ctrl+F` are configured to pass through to the terminal (via `terminal.integrated.commandsToSkipShell`) so Claude Code receives them. Other VS Code shortcuts that conflict with Claude Code:
 
@@ -247,7 +260,7 @@ For conflicting shortcuts, use Meta (Alt) variants or add custom keybindings.
 
 ### System Prompt
 
-The default system prompt is in `.devcontainer/config/defaults/main-system-prompt.md`. Override it by creating a `.claude/main-system-prompt.md` in your project directory.
+The default system prompt is in `.codeforge/config/main-system-prompt.md`. Override it by creating a `.claude/main-system-prompt.md` in your project directory.
 
 ## Custom Features
 
@@ -301,6 +314,8 @@ Three methods for providing GitHub/NPM credentials, in order of precedence:
 
 All methods persist across container rebuilds via the bind-mounted `/workspaces/.gh/` directory.
 
+4. **`.secrets` file with `CLAUDE_AUTH_TOKEN`** — Long-lived Claude auth token from `claude setup-token`. Auto-creates `~/.claude/.credentials.json` on container start.
+
 ## Agents & Skills
 
 Agents and skills are distributed across focused plugins (replacing the former `code-directive` monolith).
@@ -329,11 +344,11 @@ Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` pro
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### General Skills (21) — `skill-engine` plugin
+### General Skills (22) — `skill-engine` plugin
 
 Skills in `plugins/devs-marketplace/plugins/skill-engine/skills/` provide domain-specific coding references:
 
-`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing`
+`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing` · `worktree`
 
 ### Spec Skills (8) — `spec-workflow` plugin
 
@@ -411,20 +426,20 @@ The `setup-projects.sh` script auto-detects projects under `/workspaces/` and ma
 
 - **Authentication required**: Run `claude` once to authenticate before using `cc`
 - **Plan mode default**: The container starts in "plan" mode, which prompts for approval before making changes
-- **Config is managed by manifest**: `config/file-manifest.json` controls which files are copied and when — default `overwrite: "if-changed"` uses sha256 comparison. Persistent changes go in `.devcontainer/config/defaults/settings.json`
+- **Config is managed by manifest**: `.codeforge/file-manifest.json` controls which files are copied and when — default `overwrite: "if-changed"` uses sha256 comparison. Persistent changes go in `.codeforge/config/settings.json`
 - **GitHub auth persists**: Run `gh auth login` once or configure `.secrets`; credentials survive container rebuilds
-- **Agent Teams needs tmux**: Split panes only work inside tmux. Use the "Claude Teams (tmux)" VS Code terminal profile or `connect-external-terminal.sh` from WezTerm/iTerm2
+- **Agent Teams needs tmux**: Split panes only work inside tmux. Use the "Claude Teams (tmux)" VS Code terminal profile or `.codeforge/scripts/connect-external-terminal.sh` from WezTerm/iTerm2
 
 ## Troubleshooting
 
-Common issues and solutions. For detailed troubleshooting, see [docs/troubleshooting.md](docs/troubleshooting.md).
+Common issues and solutions. For detailed troubleshooting, see the [Troubleshooting](https://codeforge.core-directive.com/reference/troubleshooting/) page on the docs site.
 
 | Problem | Solution |
 |---------|----------|
 | `cc: command not found` | Run `source ~/.bashrc` or open a new terminal |
 | `claude` fails during startup | Background update may be in progress — wait 10s and retry |
 | GitHub push fails | Run `gh auth status` to check authentication |
-| Plugin not loading | Check `enabledPlugins` in `config/defaults/settings.json` |
+| Plugin not loading | Check `enabledPlugins` in `.codeforge/config/settings.json` |
 | Feature not installed | Check `devcontainer.json` for `"version": "none"` |
 | Tool version/status | Run `cc-tools` to list all tools with version info |
 | Full health check | Run `check-setup` to verify setup status |
@@ -432,11 +447,11 @@ Common issues and solutions. For detailed troubleshooting, see [docs/troubleshoo
 ## Further Reading
 
 **CodeForge Documentation**:
-- [Configuration Reference](docs/configuration-reference.md) — all env vars and config options
-- [Plugin System](docs/plugins.md) — plugin architecture and per-plugin docs
-- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components, disabling features
-- [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
-- [Troubleshooting](docs/troubleshooting.md) — common issues and solutions
+- [Configuration Reference](https://codeforge.core-directive.com/customization/configuration/) — all env vars and config options
+- [Plugin System](https://codeforge.core-directive.com/plugins/) — plugin architecture and per-plugin docs
+- [Optional Features](https://codeforge.core-directive.com/customization/optional-features/) — mcp-qdrant and other optional components, disabling features
+- [Keybinding Customization](https://codeforge.core-directive.com/customization/keybindings/) — resolving VS Code conflicts
+- [Troubleshooting](https://codeforge.core-directive.com/reference/troubleshooting/) — common issues and solutions
 
 **External**:
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)

package/.devcontainer/devcontainer.json

@@ -5,11 +5,23 @@
 	"workspaceFolder": "/workspaces",
 	"workspaceMount": "source=${localWorkspaceFolder},target=/workspaces,type=bind",
 
+	"initializeCommand": "bash .devcontainer/scripts/preflight.sh",
+
+	"mounts": [
+		{
+			"source": "codeforge-claude-config-${devcontainerId}",
+			"target": "/home/vscode/.claude",
+			"type": "volume"
+		}
+	],
+
 	"remoteEnv": {
 		"WORKSPACE_ROOT": "/workspaces",
-		"CLAUDE_CONFIG_DIR": "/workspaces/.claude",
+		"CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
 		"GH_CONFIG_DIR": "/workspaces/.gh",
 		"TMPDIR": "/workspaces/.tmp",
+		"TERM": "${localEnv:TERM:xterm-256color}",
+		"COLORTERM": "truecolor",
 		"CLAUDECODE": null
 	},
 
@@ -27,15 +39,20 @@
 		},
 		"GH_EMAIL": {
 			"description": "GitHub email for git config (optional)"
+		},
+		"CLAUDE_AUTH_TOKEN": {
+			"description": "Claude long-lived auth token from 'claude setup-token' (optional - sk-ant-oat01-*)",
+			"documentationUrl": "https://docs.anthropic.com/en/docs/claude-code/cli-reference#claude-setup-token"
 		}
 	},
 
 	// 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.
-	// notify-hook is last (lightweight, no dependencies).
+	// notify-hook is second-to-last (lightweight, no dependencies).
+	// dbr (devcontainer-bridge) is last — standalone binary, no dependencies.
 	"overrideFeatureInstallOrder": [
 		"ghcr.io/devcontainers/features/node",
 		"ghcr.io/devcontainers/features/github-cli",
@@ -43,7 +60,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",
@@ -63,7 +80,8 @@
 		"./features/shellcheck",
 		"./features/hadolint",
 		"./features/biome",
-		"./features/notify-hook"
+		"./features/notify-hook",
+		"ghcr.io/bradleybeddoes/devcontainer-bridge/dbr"
 	],
 
 	"features": {
@@ -82,7 +100,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",
@@ -133,17 +151,18 @@
 		"./features/notify-hook": {
 			"enableBell": true,
 			"enableOsc": true
-		}
+		},
+		"ghcr.io/bradleybeddoes/devcontainer-bridge/dbr:0.2.0": {}
 	},
 
-	"forwardPorts": [7847],
+	"forwardPorts": [],
 	"portsAttributes": {
 		"7847": {
 			"label": "Claude Dashboard",
 			"onAutoForward": "notify"
 		},
 		"*": {
-			"onAutoForward": "silent"
+			"onAutoForward": "notify"
 		}
 	},
 
@@ -188,7 +207,6 @@
 			"extensions": [
 				"wenbopan.vscode-terminal-osc-notifier",
 				"GitHub.vscode-github-actions",
-				"fabiospampinato.vscode-todo-plus",
 				"alefragnani.project-manager"
 			]
 		}

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

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 VERSION="${VERSION:-latest}"

package/.devcontainer/features/ast-grep/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 VERSION="${VERSION:-latest}"

package/.devcontainer/features/biome/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 VERSION="${VERSION:-latest}"

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

@@ -18,11 +18,6 @@
         "bash",
         "zsh",
         "both"
-      ],
-      "proposals": [
-        "bash",
-        "zsh",
-        "both"
       ]
     },
     "username": {

package/.devcontainer/features/ccburn/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # === SETUP ===

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

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # === SETUP ===

package/.devcontainer/features/ccstatusline/README.md

@@ -45,7 +45,7 @@ All widgets connected with powerline arrows (monokai theme).
 
 - **ccstatusline npm package**: Installed on-demand via `npx` (not globally)
 - **Configuration file**: `~/.config/ccstatusline/settings.json` with powerline theme
-- **Claude Code integration**: Automatically updates `.claude/settings.json`
+- **Claude Code integration**: Automatically updates `~/.claude/settings.json`
 - **Disk Usage**: Minimal (~2MB when cached by npx)
 
 ## Requirements
@@ -75,9 +75,10 @@ The feature will validate these are present and exit with an error if missing.
 - ✅ **Session Resume**: Copyable `cc --resume {sessionId}` command via custom-command widget
 - ✅ **Burn Rate Tracking**: Live ccburn compact output showing pace indicators (🧊/🔥/🚨)
 - ✅ **ANSI Colors**: High-contrast colors optimized for dark terminals
-- ✅ **Automatic Integration**: Auto-configures `.claude/settings.json`
+- ✅ **Automatic Integration**: Auto-configures `~/.claude/settings.json`
 - ✅ **Idempotent**: Safe to run multiple times
 - ✅ **Multi-user**: Automatically detects container user
+- ✅ **Config-aware**: Respects `CLAUDE_CONFIG_DIR` environment variable (defaults to `~/.claude`)
 
 ## Post-Installation Steps
 
@@ -85,7 +86,7 @@ The feature will validate these are present and exit with an error if missing.
 
 This feature automatically:
 1. Creates `~/.config/ccstatusline/settings.json` with powerline configuration
-2. Configures `.claude/settings.json` to use ccstatusline
+2. Configures `~/.claude/settings.json` to use ccstatusline
 
 **No manual steps required!**
 
@@ -105,7 +106,7 @@ You should see formatted output with powerline styling.
 
 **3. Check Claude Code integration:**
 ```bash
-cat /workspaces/.claude/settings.json | jq '.statusLine'
+cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json" | jq '.statusLine'
 ```
 
 Should show:
@@ -204,7 +205,7 @@ cat ~/.config/ccstatusline/settings.json | jq .
 echo '{"model":{"display_name":"Test"}}' | npx -y ccstatusline@latest
 
 # 3. Check Claude Code settings
-cat /workspaces/.claude/settings.json | jq '.statusLine'
+cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json" | jq '.statusLine'
 
 # 4. Manually run auto-config if needed
 configure-ccstatusline-auto
@@ -258,7 +259,7 @@ configure-ccstatusline-auto
 npm install -g ccstatusline@latest
 ```
 
-Then update `.claude/settings.json`:
+Then update `${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json`:
 ```json
 {
   "statusLine": {

package/.devcontainer/features/ccstatusline/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # Cleanup on exit
@@ -67,7 +69,7 @@ else
 fi
 
 # Widget config is managed by file-manifest.json (deployed by setup-config.sh)
-# Source: .devcontainer/config/defaults/ccstatusline-settings.json
+# Source: .codeforge/config/ccstatusline-settings.json
 # Deployed to: ~/.config/ccstatusline/settings.json (if-changed)
 # Template:    /usr/local/share/ccstatusline/settings.template.json (always)
 echo "[ccstatusline] Widget config managed by file-manifest.json"
@@ -75,6 +77,7 @@ echo "[ccstatusline] Widget config managed by file-manifest.json"
 # Create directories so wrapper doesn't fail before first post-start
 mkdir -p "${USER_HOME}/.config/ccstatusline"
 mkdir -p /usr/local/share/ccstatusline
+chown "${USERNAME}:${USERNAME}" /usr/local/share/ccstatusline
 chown "${USERNAME}:${USERNAME}" "${USER_HOME}/.config/ccstatusline" 2>/dev/null || true
 
 # Create session resume helper script for custom-command widget
@@ -190,9 +193,11 @@ if ! command -v jq &>/dev/null; then
     exit 1
 fi
 
-SETTINGS_FILE="${WORKSPACE_ROOT:-/workspaces}/.claude/settings.json"
 # Use SUDO_USER since _REMOTE_USER isn't set in post-start hooks
 USERNAME="${SUDO_USER:-vscode}"
+_USER_HOME=$(getent passwd "$USERNAME" 2>/dev/null | cut -d: -f6)
+_USER_HOME="${_USER_HOME:-/home/$USERNAME}"
+SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-${_USER_HOME}/.claude}/settings.json"
 
 # Ensure directory exists
 mkdir -p "$(dirname "${SETTINGS_FILE}")"
@@ -232,7 +237,7 @@ echo "  ccstatusline Installation Complete"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
 echo "Configuration:"
-echo "  • Source: .devcontainer/config/defaults/ccstatusline-settings.json"
+echo "  • Source: .codeforge/config/ccstatusline-settings.json"
 echo "  • Deployed to: ~/.config/ccstatusline/settings.json (by file-manifest)"
 echo "  • Template: /usr/local/share/ccstatusline/settings.template.json"
 echo "  • User: ${USERNAME}"
@@ -244,7 +249,7 @@ echo "━━━━━━━━━━━━━━━━━━━━━━━━
 echo ""
 echo "1. Widget config is deployed automatically on container start"
 echo ""
-echo "2. To customize: edit .devcontainer/config/defaults/ccstatusline-settings.json"
+echo "2. To customize: edit .codeforge/config/ccstatusline-settings.json"
 echo "   Changes deploy on next container start (if-changed)"
 echo ""
 echo "3. Test manually:"

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

@@ -18,11 +18,6 @@
         "bash",
         "zsh",
         "both"
-      ],
-      "proposals": [
-        "bash",
-        "zsh",
-        "both"
       ]
     },
     "username": {

package/.devcontainer/features/ccusage/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # === SETUP ===

package/.devcontainer/features/chromaterm/chromaterm.yml

@@ -18,7 +18,7 @@ rules:
   # File paths with optional line numbers (e.g., src/main.py:42)
   # Covers common extensions for languages used in development
   - description: File paths with line numbers
-    regex: '(?<=[\s(]|^)([a-zA-Z0-9_./-]+\.(py|ts|tsx|js|jsx|md|json|yml|yaml|toml|sh|rs|go|sql|css|html|svelte))(:(\d+))?'
+    regex: '(?:(?<=[\s(])|^)([a-zA-Z0-9_./-]+\.(py|ts|tsx|js|jsx|md|json|yml|yaml|toml|sh|rs|go|sql|css|html|svelte))(:(\d+))?'
     color:
       1: f.file_purple underline
       4: f.line_gray
@@ -31,5 +31,5 @@ rules:
 
   # Git short commit hashes (7-12 hex chars)
   - description: Git commit hashes
-    regex: '(?<=commit |merge |pick |revert |fixup )[0-9a-f]{7,40}'
+    regex: '(?:(?<=commit )|(?<=merge )|(?<=pick )|(?<=revert )|(?<=fixup ))[0-9a-f]{7,40}'
     color: f.hash_yellow

package/.devcontainer/features/chromaterm/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # ==============================

package/.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.

package/.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"
+	]
+}