Persist Claude Code configuration across workspaces

Persist Claude Code skills, settings, MCP servers, and plugins across OpenShift Dev Spaces workspaces by storing them in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup.

Claude Code configuration files
Copy link

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

Expand
Path Contents
/home/user/.claude/ Settings, plugins, custom agents, hooks, per-project memory.
/home/user/.claude.json Application settings and MCP server configurations.
Important

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
Copy link

Expand
Approach Summary Storage requirement
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. RWX for concurrent workspaces
PVC tmp copy A dedicated PVC is mounted at/tmp/claude. ApostStart command copies everything into the home directory. No init pod is required, but changes must be synced back manually before stopping the workspace. RWX for concurrent workspaces
GitOps A Git repository stores the baseline Claude Code configuration. The Dev Workspace Operator clones the repository at startup, and apostStart command copies the configuration into the home directory. No PVC required

Distribute skills and commands
Copy link

To distribute team-authored skills, commands, and agents across workspaces without persisting the full configuration, use Lola. Lola supports Claude Code and other AI assistants. For Lola setup instructions, see Distribute AI assistant skills and commands across workspaces with Lola in Additional resources.

Filter PVC mounts by workspace name
Copy link

Control which workspaces mount the PVC by adding annotations to the PVC metadata:

annotations:
  controller.devfile.io/mount-to-devworkspace-include: '<pattern>'
  controller.devfile.io/mount-to-devworkspace-exclude: '<pattern>'

mount-to-devworkspace-include mounts the PVC only to workspaces whose names match the pattern. mount-to-devworkspace-exclude mounts the PVC to all workspaces except those whose names match.

Supported patterns: exact match (name), prefix (name*), suffix (*name), contains (*name*). Matching is on the Dev Workspace resource name.

Concurrent workspace access
Copy link

Expand
Access mode Behavior
ReadWriteOnce (RWO) One workspace at a time. Two workspaces on different nodes cause a multi-attach error.
ReadWriteMany (RWX) Concurrent workspaces on different pods 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
Copy link

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.

Claude Code file reference
Copy link

Expand
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