Persist Claude Code configuration in Che workspaces

To reuse Claude Code skills, settings, MCP servers, and plugins across Che workspaces, persist the configuration in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup.

Claude Code configuration files

Claude Code stores configuration in two separate locations in the user’s home directory:

Path Contents

/home/user/.claude/

Settings, plugins, custom agents, hooks, per-project memory.

/home/user/.claude.json

Application settings and MCP server configurations.

MCP server configurations are stored in /home/user/.claude.json, a separate file at the home directory root, not inside /home/user/.claude/. Both locations must be persisted.

Claude Code writes runtime state to both paths during every session, including session files, caches, and usage statistics. These paths must be writable. Mounting a read-only ConfigMap or Secret directly to these paths causes Claude Code to fail.

Available approaches

Approach Summary

Share Claude Code configuration with PVC direct mount

Both /home/user/.claude/ and /home/user/.claude.json are mounted directly from a dedicated PVC. All changes persist automatically. Requires a one-time init pod to pre-create .claude.json.

Share Claude Code configuration with PVC tmp copy

A dedicated PVC is mounted at /tmp/claude. A postStart command copies everything into the home directory. No init pod is required, but changes must be synced back manually before stopping the workspace.

Share Claude Code configuration across workspaces with GitOps

A Git repository stores the baseline Claude Code configuration. The DevWorkspace Operator clones the repository at startup, and a postStart command copies the configuration into the home directory.

PVC shared options

The following options apply to both PVC approaches (direct mount and tmp copy).

Filtering by workspace name

Control which workspaces mount the PVC by adding annotations:

annotations:
  controller.devfile.io/mount-to-devworkspace-include: '<pattern>' (1)
  controller.devfile.io/mount-to-devworkspace-exclude: '<pattern>' (2)
1 Mount the PVC only to workspaces whose names match the pattern.
2 Mount the PVC to all workspaces except those whose names match the pattern.

Supported patterns: (all), prefix, suffix, *contains, exact-name. Matching is on the DevWorkspace resource name.

Concurrent workspaces

Access mode Behavior

ReadWriteOnce (RWO)

One workspace at a time. Two workspaces on different nodes cause a multi-attach error.

ReadWriteMany (RWX)

Concurrent workspaces work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX.

Compatibility with persistUserHome

A dedicated PVC mounted at /home/user/.claude and the persistent home PVC mounted at /home/user/ coexist correctly as nested mounts. Writes to /home/user/.claude/ go to the dedicated PVC. Writes to other paths under /home/user/ go to the persistent home PVC.

If you only need persistence within a single workspace and not cross-workspace sharing, persistUserHome alone is sufficient.

Limitations

  • Requires manual PVC setup per user namespace.

  • RWX storage may not be available on all clusters.

  • On clusters with only block storage and multi-AZ topology, the direct mount init pod may cause scheduling failures. Use the tmp copy approach instead.

Claude Code file reference

Path Purpose Size Regeneratable

/home/user/.claude/settings.json

Permissions, hooks, enabled plugins, model preferences.

Small

No

/home/user/.claude/settings.local.json

Local setting overrides.

Small

No

/home/user/.claude/CLAUDE.md

User-level instructions for Claude.

Small

No

/home/user/.claude/plugins/

Installed plugins and caches.

Large (100 MB+)

Partially

/home/user/.claude/agents/

Custom agent definitions.

Small

No

/home/user/.claude/hooks/

Shell scripts for session lifecycle.

Small

No

/home/user/.claude/projects/

Per-project memory and settings.

Medium

No

/home/user/.claude.json

Application settings and MCP server configurations.

Small

No

/home/user/.claude/history.jsonl

Conversation history.

Large

Optional

/home/user/.claude/plugins/cache/

Plugin download cache.

Large

Yes
Additional resources