docs: Add Claude Code configuration persistence guides by akurinnoy · Pull Request #3138 · eclipse-che/che-docs

akurinnoy · 2026-06-30T13:37:13Z

What does this pull request change?

Adds a new "AI coding tools in workspaces" section to the User Guide with documentation on persisting Claude Code configuration across workspaces.

New pages:

AI coding tools in workspaces - top-level section, extensible for other tools later
Persisting Claude Code configuration - overview of config file locations (~/.claude/, ~/.claude.json), comparison of available approaches, file reference table
Sharing configuration with a dedicated PVC - step-by-step guide with two options: direct mount (Option A) and full /tmp copy (Option B)
Sharing configuration with GitOps - concept page describing the Git-based approach using DWO's project-clone init container
Troubleshooting Claude Code configuration persistence - 7 known issues with symptoms, causes, and solutions

What issues does this pull request fix or reference?

resolves eclipse-che/che#23846

Specify the version of the product this pull request applies to

Pull Request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

Any procedure:
- Successfully tested.
Any page or link rename:
- The page contains a redirection for the previous URL.
- Propagate the URL change in:
  - Dashboard default branding data
Builds on Eclipse Che hosted by Red Hat.
the Validate language on files added or modified step reports no vale warnings.

github-actions · 2026-06-30T13:37:24Z

Click here to review and test in web IDE:

github-actions · 2026-06-30T13:37:25Z

⚡️ Deploying pull request preview...

Add documentation for persisting and sharing Claude Code configuration across Eclipse Che workspaces under a new "AI coding tools in workspaces" section in the User Guide. New pages: - Overview of Claude Code configuration files and available approaches - Dedicated PVC with automount (Option A: direct mount, Option B: /tmp copy) - GitOps approach using a central Git repository - Troubleshooting known issues with configuration persistence Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>

- Rename all pages to imperative titles (CQA P10) - Split PVC page into two separate procedures: direct mount and tmp copy (CQA P12) - Change overview content type from ASSEMBLY to CONCEPT (CQA P3/P5) - Rewrite abstracts to lead with user goal (CQA P11/JTBD) - Merge adjacent admonitions (CQA Q10) - Use {prod-home} consistently, replace bare ~/ paths (CQA Q20) - Add full GitOps procedure with devfile snippets (JTBD) - Split multi-command init pod step into separate steps (CQA Q14) - Replace tail -f /dev/null with restartPolicy: Never in init pod - Move persistUserHome compatibility note to overview (CQA Q5) - Move non-troubleshooting section out of troubleshooting page - Rewrite troubleshooting intro to user-centric language (CQA Q4/Q5) - Add "how it works" flow summaries to both PVC procedure pages - Add page-aliases for old filenames to preserve redirects Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>

- Add DWO automount docs link to additional resources - Fix asterisk rendering in pattern list - Move PVC shared options (filtering, concurrent workspaces, persistUserHome compatibility, limitations) from overview to individual PVC procedure pages - Add include/exclude annotations as multi-attach workaround in troubleshooting - Add prerequisite about stopping workspaces before PVC creation on direct mount page Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>

akurinnoy · 2026-07-14T14:06:08Z

Rebased onto current main to pick up the 7.120 version bump.

dkwon17 · 2026-07-15T15:56:26Z

+
+. Create the init pod to initialize the PVC.
+
+The `{prod-home}/.claude.json` subPath target must exist as a *file* on the PVC before any workspace starts. Without this step, {kubernetes} kubelet creates a directory instead of a file, and Claude Code fails to parse it.


Suggested change

The `{prod-home}/.claude.json` subPath target must exist as a *file* on the PVC before any workspace starts. Without this step, {kubernetes} kubelet creates a directory instead of a file, and Claude Code fails to parse it.

The `{prod-home}/.claude.json` subPath target must exist as a *file* on the PVC before any workspace starts. Without this step, the {kubernetes} kubelet creates a directory instead of a file, and Claude Code fails to parse it.

dkwon17 · 2026-07-15T15:58:23Z

+| 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.


Suggested change

| 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.

| 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.

Just a suggestion

dkwon17 · 2026-07-15T16:05:41Z

+
+* For concurrent workspaces: a storage class that supports `ReadWriteMany` (RWX) access mode, such as AWS EFS or NFS. Standard block storage (gp2, gp3) supports only `ReadWriteOnce` (RWO).
+
+* All running workspaces must be stopped before creating the PVC. If a workspace is running when the PVC with the automount label is created, `{prod-home}/.claude.json` may be mounted as a directory instead of a file.


Suggested change

* All running workspaces must be stopped before creating the PVC. If a workspace is running when the PVC with the automount label is created, `{prod-home}/.claude.json` may be mounted as a directory instead of a file.

* All running workspaces in the the {orch-namespace} must be stopped before creating the PVC. If a workspace is running when the PVC with the automount label is created, `{prod-home}/.claude.json` may be mounted as a directory instead of a file.

dkwon17 · 2026-07-15T16:06:09Z

+. A one-time init pod creates an empty skeleton on the PVC: `{}` in `.claude.json` and an empty `.claude/` directory.
+. The first workspace starts. The PVC mounts to `{prod-home}/.claude/` and `{prod-home}/.claude.json`. Claude Code sees valid, empty configuration.
+. You configure Claude Code — install plugins, add MCP servers, change settings. All writes go directly to the PVC.
+. The second workspace starts. The same PVC mounts, and all configuration from the previous workspace is available.


Suggested change

. The second workspace starts. The same PVC mounts, and all configuration from the previous workspace is available.

. A second workspace starts. The same PVC mounts, and all configuration from the previous workspace is available.

dkwon17 · 2026-07-15T20:40:01Z

+. The first workspace starts. The PVC mounts at `/tmp/claude` (empty on first run). The `postStart` command copies configuration into `{prod-home}/.claude/` and `{prod-home}/.claude.json`. On first run, nothing is copied.
+. You configure Claude Code — install plugins, add MCP servers, change settings. All writes go to the home directory, not the PVC.
+. Before stopping the workspace, you sync changes back to the PVC at `/tmp/claude`.
+. The second workspace starts. The `postStart` command copies the saved configuration from the PVC into the home directory.


Suggested change

. The second workspace starts. The `postStart` command copies the saved configuration from the PVC into the home directory.

. A second workspace starts. The `postStart` command copies the saved configuration from the PVC into the home directory.

dkwon17 · 2026-07-15T20:42:26Z

+
+== Compatibility with `persistUserHome`
+
+A dedicated PVC mounted at `{prod-home}/.claude` and the persistent home PVC mounted at `{prod-home}/` coexist correctly as nested mounts. Writes to `{prod-home}/.claude/` go to the dedicated PVC. Writes to other paths under `{prod-home}/` go to the persistent home PVC.


Writes to {prod-home}/.claude/ go to the dedicated PVC.

This is not true in this case, is that right? (because user must sync changes back to the PVC?)

btjd · 2026-07-15T21:27:30Z

+
+[subs="+quotes,+attributes"]
+----
+$ {orch-cli} wait pod/claude-config-init --for=condition=Ready --timeout=120s


Should the check be for condition 'Completed' instead of 'Ready'? My understanding is that init pods with restartPolicy: Never don't reach Ready condition and they go to directly to completed?

btjd · 2026-07-15T21:39:26Z

+      commandLine: |
+        cp -a /projects/claude-config/.claude/. {prod-home}/.claude/ 2>/dev/null || true
+        cp /projects/claude-config/.claude.json {prod-home}/.claude.json 2>/dev/null || true
+      component: __<editor_container>__ # <1>


nitpick, should we clarify how <editor_container> can be obtained? Maybe use 'kubectl get devworkspace <workspace_name> -o yaml?

akurinnoy requested review from a team, deerskindoll, gtrivedi88 and mkuznyetsov as code owners June 30, 2026 13:37

akurinnoy requested a review from azatsarynnyy June 30, 2026 13:37

akurinnoy requested review from btjd, dkwon17, rohanKanojia and tolusha June 30, 2026 13:38

akurinnoy force-pushed the docs/persist-claude-code-config branch from 6ffdabe to 97c6dea Compare June 30, 2026 13:53

rohanKanojia reviewed Jul 1, 2026

View reviewed changes

Comment thread modules/end-user-guide/pages/persisting-claude-code-configuration.adoc Outdated

akurinnoy marked this pull request as draft July 1, 2026 12:19