[DOCS] `--resume` docs conflict on cross-worktree session resumption

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/36855

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Checked the current docs on 2026-05-07. This issue is only partially resolved and should stay open.

checked docs, not resolved yet

Issue #44908 Verification

Title: [DOCS] --resume docs conflict on cross-worktree session resumption
Issue Date: 2026-04-07
Verification Date: 2026-06-12
Status: RESOLVED

---

Issue Summary

This issue reports that the --resume documentation was inconsistent about whether Claude Code can resume sessions from other worktrees in the same repository and whether selecting one of those sessions resumes directly in that worktree. The reporter cited three pages: how-claude-code-works, common-workflows, and cli-reference, and referenced changelog v2.1.94 ("Improved --resume to resume sessions from other worktrees of the same repo directly instead of printing a cd command").

---

Verification Results

Claim 1: how-claude-code-works says resumed sessions are only visible from the current directory

Status: RESOLVED

At https://code.claude.com/docs/en/how-claude-code-works, line 103: "Each Claude Code conversation is a session tied to your current directory. The /resume picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See Manage sessions for the full list of picker shortcuts and how name resolution works."

Verdict: The "Work across branches" section no longer claims the picker is limited to the current directory. It now states that the picker defaults to the current worktree and can be widened to other worktrees or projects, which matches the changelog behavior.

---

Claim 2: common-workflows distinguishes --continue from --resume and says the picker includes worktree sessions from the same repo

Status: RESOLVED

At https://code.claude.com/docs/en/common-workflows, line 460: "## Resume previous conversations"

At https://code.claude.com/docs/en/common-workflows, lines 464-468: "`bash\nclaude --continue\n`\nThis resumes the most recent session in the current directory; if there isn't one yet, it prints No conversation found to continue and exits. Use claude --resume to choose from a list, or /resume` from inside a running session. See Manage sessions for naming, branching, and the full picker reference."

At https://code.claude.com/docs/en/sessions, line 25: "claude --continue | Resumes the most recent session in the current directory"

At https://code.claude.com/docs/en/sessions, line 26: "claude --resume | Opens the [session picker](#use-the-session-picker)"

At https://code.claude.com/docs/en/sessions, line 35: "Sessions are stored per project directory. By default the session picker shows interactive sessions from the current worktree, plus sessions started elsewhere that added the current directory with /add-dir. ... Use Ctrl+W to widen to all worktrees of the repository or Ctrl+A to widen to every project on this machine."

Verdict: The current-directory behavior of --continue and the picker-based behavior of --resume are now documented consistently in common-workflows and the canonical sessions page. The "same git repository, including worktrees" rule is described on the sessions page, which common-workflows explicitly links to as the full picker reference.

---

Claim 3: cli-reference --resume flag description does not mention same-repo worktree behavior

Status: RESOLVED

At https://code.claude.com/docs/en/cli-reference, line 104: "--resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session. The picker and name search include sessions that added this directory with /add-dir; passing a session ID searches only the current project directory and its git worktrees. As of v2.1.144, background sessions appear in the picker marked with bg"

Verdict: The --resume flag description now explicitly states that "passing a session ID searches only the current project directory and its git worktrees," which aligns with the cross-worktree behavior described elsewhere.

---

Claim 4: Docs do not state that selecting a session from another worktree resumes directly in that worktree instead of printing a cd command

Status: RESOLVED

At https://code.claude.com/docs/en/sessions, line 37: "Selecting a session from another worktree of the same repository resumes it in place. Selecting a session from an unrelated project copies a cd and resume command to your clipboard instead."

At https://code.claude.com/docs/en/sessions, line 39: "Resuming by name resolves across the current repository and its worktrees. Both forms look for an exact match and resume it directly even if it lives in a different worktree"

Verdict: The direct cross-worktree resumption behavior is now documented explicitly in the Manage sessions page, including the contrast with the clipboard cd flow for unrelated projects.

---

Current State

| Claim | Status |
|-------|--------|
| how-claude-code-works no longer limits /resume visibility to the current directory | RESOLVED |
| --continue and cross-worktree --resume are now distinguished consistently | RESOLVED |
| cli-reference --resume entry now mentions same-repository worktree behavior | RESOLVED |
| Direct cross-worktree resumption is documented in the Manage sessions page | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/how-claude-code-works
• Lines 101-103: The "Work across branches" section now says the /resume picker defaults to the current worktree and can be widened to other worktrees or projects, and links to the Manage sessions page.

• URL: https://code.claude.com/docs/en/common-workflows
• Lines 460-468: The "Resume previous conversations" section documents claude --continue as resuming the most recent session in the current directory and points readers to claude --resume and the Manage sessions page for the full picker reference.

• URL: https://code.claude.com/docs/en/sessions
• Lines 25-26: Distinguish claude --continue (resumes the most recent session in the current directory) from claude --resume (opens the session picker).
• Lines 33-39: Explain picker scope, widening to repository worktrees via Ctrl+W, direct in-place resumption for sessions from another worktree in the same repository, and name resolution that spans worktrees.

• URL: https://code.claude.com/docs/en/cli-reference
• Line 104: The --resume flag description now states that "passing a session ID searches only the current project directory and its git worktrees."

---

Conclusion & Recommendation

Primary Concern: The docs were inconsistent about whether --resume could see and resume sessions from other worktrees of the same repository, and whether selecting one of those sessions would resume directly in that worktree.

Resolution Status: RESOLVED

Recommendation: CLOSE

The four substantive concerns raised in the issue are all addressed in the current docs: the picker scoping is corrected in how-claude-code-works, the --continue vs --resume distinction is preserved in common-workflows, the cli-reference --resume entry now mentions worktree behavior, and the direct cross-worktree resumption flow is documented in the Manage sessions page.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.