feat(config): move .claude to home directory with named volume and auth token support (#3)

* Move .claude config from /workspaces to home directory with named volume

- Change CLAUDE_CONFIG_DIR from /workspaces/.claude to ~/.claude
- Add Docker named volume (per-instance via ${devcontainerId}) for persistence
- Add CLAUDE_AUTH_TOKEN secret support with auto .credentials.json creation
- Replace setup-symlink-claude.sh with setup-migrate-claude.sh (one-time migration)
- Fix named volume root ownership via sudo chown on startup
- Update scope guard allowlist to resolve $HOME dynamically
- Update protected-files guard regex to cover .credentials.json
- Update all feature heredocs, poststart hooks, and docs

* Harden auth token handling, migration, and volume ownership

Security and robustness fixes from PR review:

- setup-auth.sh: Replace unquoted heredoc with printf '%s' to prevent
  shell injection via CLAUDE_AUTH_TOKEN metacharacters (H1)
- setup-auth.sh: Add sk-ant-* format validation on token (L1)
- setup-auth.sh: Check/fix 600 permissions on existing .credentials.json (L2)
- setup-auth.sh: Use ${CLAUDE_CONFIG_DIR:-$HOME/.claude} pattern
  consistently with other scripts (M3)
- setup-auth.sh: Document /proc token visibility limitation (M2)
- setup-migrate-claude.sh: Add idempotency check — skip silently when
  destination already has content (H2)
- setup-migrate-claude.sh: Broaden trigger — migrate all content, not
  just when .credentials.json exists (L3)
- setup-migrate-claude.sh: Add symlink protection on old directory (M1)
- setup-migrate-claude.sh: Use --no-dereference with cp (M1)
- setup-migrate-claude.sh: Use ${CLAUDE_CONFIG_DIR} pattern (L4)
- setup.sh: Log warning on sudo chown failure instead of silent
  suppression (M4)

* Address CodeRabbit review findings (1, 2, 6, 7)

- CHANGELOG.md: Add #### Documentation subsection under Changed, add
  #### Scripts subsection under Removed for consistent structure
- CLAUDE.md: Document CLAUDE_AUTH_TOKEN, .credentials.json auto-creation,
  skip-if-exists behavior, sk-ant-* validation, and named volume persistence
- setup-auth.sh: Detect printf subshell write failure — report warning
  instead of false success when .credentials.json write fails
- setup-migrate-claude.sh: Verify cp exit status before printing success —
  warn if copy failed instead of unconditional "Migration complete"
- docs/reference/changelog.md: Mirror CHANGELOG structure fixes

Findings 3-5 (feature $HOME fallback) confirmed as false positives:
postStartCommand runs as vscode user, CLAUDE_CONFIG_DIR is exported
by setup.sh before hooks execute.

* Address remaining CodeRabbit review findings (3, 4, 5, 8, 9, 10)

- Fix hardcoded /home/vscode/.claude in changelog, use portable ~/.claude
- Remove implementation detail "(leading dot)" from changelog entry
- Set AUTH_CONFIGURED=true when credentials already exist (fixes false
  "No tokens provided" summary)
- Update docs site settings.json deployment path to ~/.claude
- Harden $HOME fallback across all scripts: resolve target user's home
  via SUDO_USER/USER/vscode chain instead of relying on $HOME (guards
  against root context in feature installs and hooks)
- Add CLAUDE_CONFIG_DIR documentation to ccstatusline and mcp-qdrant
  feature READMEs
- Fix stale .claude/settings.json references in ccstatusline README

* Harden shell scripts and fix stale docs from CodeRabbit review

- Replace eval tilde expansion with getent passwd lookup in all
  PR-scoped scripts (setup-auth, setup-migrate, ccstatusline,
  mcp-qdrant install + poststart hook) to prevent shell injection
  via SUDO_USER/USER environment variables
- JSON-escape auth token value before writing .credentials.json
- Create credential directory with umask 077 (was default 755)
- Fix mcp-qdrant chown to use resolved _USERNAME instead of
  hardcoded vscode or $(id -un)
- Update ccstatusline README verification commands to respect
  CLAUDE_CONFIG_DIR environment variable
- Sync docs site changelog with devcontainer CHANGELOG fixes
  (~/. claude path, remove "(leading dot)" aside)

* fix(migration): harden migration script and add .env deprecation guard

Migration script:
- Switch from cp -rn to cp -a (archive mode) for faithful copy
- Marker-based idempotency instead of checking destination contents
- Verify critical files (.claude.json, plugins/, .credentials.json)
- Fix ownership after copy (source may have different uid)
- Rename old directory to .bak on success

Setup.sh:
- Detect stale CLAUDE_CONFIG_DIR=/workspaces/.claude in .env
- Override to $HOME/.claude with warning
- Auto-comment the stale line on disk

---------

Co-authored-by: AnExiledDev <AnExiledDev@users.noreply.github.com>

Author: AnExiledDev

.devcontainer/.env.example

@@ -1,9 +1,8 @@
 # CodeForge Environment Configuration
 # Copy to .env and customize. .env is gitignored.
 
-# Paths
-CLAUDE_CONFIG_DIR=/workspaces/.claude
-# CONFIG_SOURCE_DIR is derived from script location; uncomment to override:
+# Paths (defaults shown — uncomment to override)
+# CLAUDE_CONFIG_DIR=$HOME/.claude
 # CONFIG_SOURCE_DIR=/custom/path/to/config
 
 # Setup: copy config files to CLAUDE_CONFIG_DIR (per config/file-manifest.json)

.devcontainer/.secrets.example

@@ -10,3 +10,6 @@ GH_EMAIL=
 
 # NPM auth token for registry.npmjs.org
 NPM_TOKEN=
+
+# Claude long-lived auth token (from 'claude setup-token')
+CLAUDE_AUTH_TOKEN=

.devcontainer/CHANGELOG.md

@@ -9,9 +9,37 @@
 
 ### Changed
 
+#### Configuration
+- Moved `.claude` directory from `/workspaces/.claude` to `~/.claude` (home directory)
+- Added Docker named volume for persistence across rebuilds (per-instance isolation via `${devcontainerId}`)
+- `CLAUDE_CONFIG_DIR` now defaults to `~/.claude`
+
+#### Authentication
+- Added `CLAUDE_AUTH_TOKEN` support in `.secrets` for long-lived tokens from `claude setup-token`
+- Auto-creates `.credentials.json` from token on container start (skips if already exists)
+- Added `CLAUDE_AUTH_TOKEN` to devcontainer.json secrets declaration
+
+#### Security
+- Protected-files-guard now blocks modifications to `.credentials.json`
+- Replaced `eval` tilde expansion with `getent passwd` lookup across all scripts (prevents shell injection via `SUDO_USER`/`USER`)
+- Auth token value is now JSON-escaped before writing to `.credentials.json`
+- Credential directory created with restrictive umask (700) matching credential file permissions (600)
+
 #### Status Bar
 - **ccstatusline line 1** — distinct background colors for each token widget (blue=input, magenta=output, yellow=cached, green=total), bold 2-char labels (In, Ou, Ca, Tt) fused to data widgets, `rawValue: true` on model widget to strip "Model:" prefix, restored spacing between token segments
 
+#### Scripts
+- Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
+- Auto-migrates from `/workspaces/.claude/` if `.credentials.json` present
+- `chown` in mcp-qdrant poststart hooks now uses resolved `_USERNAME` instead of hardcoded `vscode` or `$(id -un)`
+- **Migration script hardened** — switched from `cp -rn` to `cp -a` (archive mode); added marker-based idempotency, critical file verification, ownership fixup, and old-directory rename
+- **`.env` deprecation guard** — `setup.sh` detects stale `CLAUDE_CONFIG_DIR=/workspaces/.claude` in `.env`, overrides to `$HOME/.claude`, and auto-comments the line on disk
+
+#### Documentation
+- All docs now reference `~/.claude` as default config path
+- Added `CLAUDE_AUTH_TOKEN` setup flow to README, configuration reference, and troubleshooting
+- ccstatusline README verification commands now respect `CLAUDE_CONFIG_DIR`
+
 ### Fixed
 
 #### Plugin Marketplace
@@ -29,6 +57,9 @@
 
 ### Removed
 
+#### Scripts
+- `setup-symlink-claude.sh` — no longer needed with native home directory location
+
 #### VS Code Extensions
 - **Todo+** (`fabiospampinato.vscode-todo-plus`) — removed from devcontainer extensions
 

.devcontainer/CLAUDE.md

@@ -31,7 +31,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `devcontainer.json` | Container definition: image, features, mounts |
 | `.env` | Boolean flags controlling setup steps |
 
-Config files deploy via `file-manifest.json` on every container start. Most deploy to `/workspaces/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
+Config files deploy via `file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
 
 ## Commands
 
@@ -76,14 +76,21 @@ Rules in `config/defaults/rules/` deploy to `.claude/rules/` on every container
 
 | Variable | Value |
 |----------|-------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` |
+| `CLAUDE_AUTH_TOKEN` | Long-lived token from `claude setup-token` (optional, via `.secrets` or Codespaces secrets) |
 | `ANTHROPIC_MODEL` | `claude-opus-4-6` |
 | `WORKSPACE_ROOT` | `/workspaces` |
 | `TERM` | `${localEnv:TERM:xterm-256color}` (via `remoteEnv` — forwards host TERM, falls back to 256-color) |
 | `COLORTERM` | `truecolor` (via `remoteEnv` — enables 24-bit color support) |
 
 All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
 
+## Authentication & Persistence
+
+The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
+
+**Token authentication:** Set `CLAUDE_AUTH_TOKEN` in `.devcontainer/.secrets` (or as a Codespaces secret) with a long-lived token from `claude setup-token`. On container start, `setup-auth.sh` auto-creates `~/.claude/.credentials.json` with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match `sk-ant-*` format.
+
 ## Modifying Behavior
 
 1. **Change model**: Edit `config/defaults/settings.json` → `"model"` field

.devcontainer/README.md

@@ -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.
 
@@ -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` |
@@ -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).

.devcontainer/devcontainer.json

@@ -5,9 +5,17 @@
 	"workspaceFolder": "/workspaces",
 	"workspaceMount": "source=${localWorkspaceFolder},target=/workspaces,type=bind",
 
+	"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}",
@@ -29,6 +37,10 @@
 		},
 		"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"
 		}
 	},
 

.devcontainer/docs/configuration-reference.md

@@ -23,7 +23,7 @@ These control what `setup.sh` does on each container start. Copy `.env.example`
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Where Claude Code config files are stored |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Where Claude Code config files are stored |
 | `CONFIG_SOURCE_DIR` | `(auto-detected)` | Source directory for config defaults |
 | `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` |
 | `SETUP_ALIASES` | `true` | Add cc/claude/ccraw/cc-tools aliases to shell |
@@ -42,7 +42,7 @@ These environment variables are set in every terminal session inside the contain
 | Variable | Value | Description |
 |----------|-------|-------------|
 | `WORKSPACE_ROOT` | `/workspaces` | Workspace root directory |
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.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) |
@@ -88,6 +88,9 @@ GH_TOKEN=ghp_your_token_here
 GH_USERNAME=your-github-username
 GH_EMAIL=your-email@example.com
 NPM_TOKEN=npm_your_token_here
+CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here
 ```
 
+The `CLAUDE_AUTH_TOKEN` is a long-lived token from `claude setup-token`. When set, `setup-auth.sh` creates `~/.claude/.credentials.json` on container start (skips if already exists).
+
 Environment variables with the same names take precedence over `.secrets` file values (useful for Codespaces).

.devcontainer/docs/keybindings.md

@@ -78,7 +78,7 @@ Edit `config/defaults/keybindings.json` to remap Claude Code actions to non-conf
 }
 ```
 
-The keybindings file is copied to `/workspaces/.claude/keybindings.json` on container start (controlled by `file-manifest.json`).
+The keybindings file is copied to `~/.claude/keybindings.json` on container start (controlled by `file-manifest.json`).
 
 ## Claude Code Keybinding Reference
 

.devcontainer/docs/troubleshooting.md

@@ -32,6 +32,11 @@ Common issues and solutions for the CodeForge devcontainer.
 - Or configure `.devcontainer/.secrets` with `GH_TOKEN` for automatic auth on container start.
 - Credentials persist in `/workspaces/.gh/` across rebuilds.
 
+**Problem**: Claude auth token not taking effect in Codespaces.
+
+- When `CLAUDE_AUTH_TOKEN` is set via Codespaces secrets, it persists as an environment variable for the entire container lifetime. The `unset` in `setup-auth.sh` only clears it in the child process. This is a Codespaces platform limitation.
+- If `.credentials.json` already exists, the token injection is skipped (idempotent). Delete `~/.claude/.credentials.json` to force re-creation from the token.
+
 **Problem**: Git push fails with permission error.
 
 - Run `gh auth status` to verify authentication.
@@ -119,7 +124,7 @@ Common issues and solutions for the CodeForge devcontainer.
 
 ## How to Reset to Defaults
 
-1. **Reset config files**: Delete `/workspaces/.claude/` and restart the container. `setup-config.sh` will recopy all files from `config/defaults/`.
+1. **Reset config files**: Delete `~/.claude/` and restart the container. `setup-config.sh` will recopy all files from `config/defaults/`.
 
 2. **Reset aliases**: Delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash /workspaces/.devcontainer/scripts/setup-aliases.sh`.
 

.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,17 +75,18 @@ 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
 
 ### ✅ Configuration is Automatic
 
 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": {