From 36ad28443993adc476edb78c51272df3f8777743 Mon Sep 17 00:00:00 2001 From: "Tobias L. Maier" Date: Fri, 24 Apr 2026 00:43:35 +0200 Subject: [PATCH] docs(claude-code): add plugins volume overlay to mount guidance The plugins/ subdirectory stores hardcoded absolute paths that break when ~/.claude/ is shared between host and container. Document the fix: overlay plugins/ with a per-container named Docker volume. --- src/claude-code/NOTES.md | 22 +++++++++++++++++----- src/claude-code/README.md | 22 +++++++++++++++++----- src/claude-code/devcontainer-feature.json | 2 +- 3 files changed, 35 insertions(+), 11 deletions(-) diff --git a/src/claude-code/NOTES.md b/src/claude-code/NOTES.md index ee84484..c2ed972 100644 --- a/src/claude-code/NOTES.md +++ b/src/claude-code/NOTES.md @@ -25,22 +25,34 @@ When `yoloAlias` is set to `true`, a `yolo` shell alias is created that expands The native binary automatically updates in the background. Update checks are performed on startup and periodically while running. To disable auto-updates, set the `DISABLE_AUTOUPDATER=1` environment variable. -## Manual config for `devcontainer.json` +## Persisting configuration across container rebuilds -Mount the local `~/.claude/` directory into the Dev Container. -Add the following mount to the `devcontainer.json` file. -Replace `vscode` with the actual name of your user (see `remoteUser` property). +To share your Claude Code configuration, conversation history, and credentials between your host and the Dev Container, mount `~/.claude/` into the container. -```json +**Important:** The `plugins/` subdirectory stores hardcoded absolute paths (e.g., `/home/vscode/.claude/plugins/...`). When the same directory is read from the host (where the path is `/Users//.claude/...`), these paths are invalid, causing a `corrupted installLocation` error. To avoid this, overlay `plugins/` with a per-container Docker volume. + +Add the following to your `devcontainer.json`. Replace `/home/vscode` with the actual home directory of your remote user (see `remoteUser` property). + +```jsonc "mounts": [ { "source": "${localEnv:HOME}/.claude", "target": "/home/vscode/.claude", "type": "bind" + }, + { + "source": "claude-plugins-${devcontainerId}", + "target": "/home/vscode/.claude/plugins", + "type": "volume" } ], ``` +- The bind mount shares your full `~/.claude/` directory (settings, credentials, conversation history, etc.) with the container. +- The volume mount overlays `plugins/` with a named Docker volume, isolating it from the host. Docker creates this volume automatically on first use. +- `${devcontainerId}` is unique per project and stable across rebuilds, so each Dev Container gets its own plugins volume. +- `~/.claude/` must exist on the host. Run Claude Code once on your host, or create it manually: `mkdir -p ~/.claude`. + ## Chrome Integration (`claude --chrome`) Claude Code supports a Chrome integration via `claude --chrome`. To use this inside a Dev Container, combine the `claude-code` feature with the [`chrome`](https://github.com/tmaier/devcontainer-features/tree/main/src/chrome) feature configured for VNC display mode: diff --git a/src/claude-code/README.md b/src/claude-code/README.md index 16482df..2c22c6e 100644 --- a/src/claude-code/README.md +++ b/src/claude-code/README.md @@ -51,22 +51,34 @@ When `yoloAlias` is set to `true`, a `yolo` shell alias is created that expands The native binary automatically updates in the background. Update checks are performed on startup and periodically while running. To disable auto-updates, set the `DISABLE_AUTOUPDATER=1` environment variable. -## Manual config for `devcontainer.json` +## Persisting configuration across container rebuilds -Mount the local `~/.claude/` directory into the Dev Container. -Add the following mount to the `devcontainer.json` file. -Replace `vscode` with the actual name of your user (see `remoteUser` property). +To share your Claude Code configuration, conversation history, and credentials between your host and the Dev Container, mount `~/.claude/` into the container. -```json +**Important:** The `plugins/` subdirectory stores hardcoded absolute paths (e.g., `/home/vscode/.claude/plugins/...`). When the same directory is read from the host (where the path is `/Users//.claude/...`), these paths are invalid, causing a `corrupted installLocation` error. To avoid this, overlay `plugins/` with a per-container Docker volume. + +Add the following to your `devcontainer.json`. Replace `/home/vscode` with the actual home directory of your remote user (see `remoteUser` property). + +```jsonc "mounts": [ { "source": "${localEnv:HOME}/.claude", "target": "/home/vscode/.claude", "type": "bind" + }, + { + "source": "claude-plugins-${devcontainerId}", + "target": "/home/vscode/.claude/plugins", + "type": "volume" } ], ``` +- The bind mount shares your full `~/.claude/` directory (settings, credentials, conversation history, etc.) with the container. +- The volume mount overlays `plugins/` with a named Docker volume, isolating it from the host. Docker creates this volume automatically on first use. +- `${devcontainerId}` is unique per project and stable across rebuilds, so each Dev Container gets its own plugins volume. +- `~/.claude/` must exist on the host. Run Claude Code once on your host, or create it manually: `mkdir -p ~/.claude`. + ## Chrome Integration (`claude --chrome`) Claude Code supports a Chrome integration via `claude --chrome`. To use this inside a Dev Container, combine the `claude-code` feature with the [`chrome`](https://github.com/tmaier/devcontainer-features/tree/main/src/chrome) feature configured for VNC display mode: diff --git a/src/claude-code/devcontainer-feature.json b/src/claude-code/devcontainer-feature.json index 486629b..617bd8c 100644 --- a/src/claude-code/devcontainer-feature.json +++ b/src/claude-code/devcontainer-feature.json @@ -1,6 +1,6 @@ { "id": "claude-code", - "version": "2.2.0", + "version": "2.2.1", "name": "Claude Code", "description": "Installs Claude Code CLI for AI-powered development assistance", "options": {