Claude Code configuration persistence

Persist Claude Code skills, settings, MCP servers, and plugins across Che 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

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 Storage requirement

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.

RWX for concurrent workspaces

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.

RWX for concurrent workspaces

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.

No PVC required

Distribute skills and commands

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

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

  • controller.devfile.io/mount-to-devworkspace-include: '<pattern>' mounts the PVC only to workspaces whose names match the pattern.

  • controller.devfile.io/mount-to-devworkspace-exclude: '<pattern>' 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 DevWorkspace resource name.

Concurrent workspace access

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

For the direct mount approach, 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.

For the tmp copy approach, the dedicated PVC mounted at /tmp/claude and the persistent home PVC mounted at /home/user/ do not conflict because they use different mount points. If the devfile includes a postStart command, it copies configuration from the PVC into the home directory at workspace start. Otherwise, you must copy the configuration manually. Changes must be synced back to the PVC manually before stopping the workspace.

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

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