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.

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