[DOCS] [Troubleshooting] Sessions launched from VS Code integrated terminal or any shell that inherited Claude Code env vars — v2.1.170 transcript/resume fix is not mentioned in the troubleshooting or VS Code pages

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/troubleshoot-install

Section/Topic

The "Authentication" / "Provider credentials" troubleshooting section, and the "Resume a session" section of the VS Code page, do not acknowledge the v2.1.170 fix for sessions launched from the VS Code integrated terminal or any shell that inherited Claude Code environment variables (notably CLAUDECODE=1 and CLAUDE_CODE_ENTRYPOINT). Users hit by this before v2.1.170 will not learn that the issue is fixed, and users who upgrade will not know to clean stale entries that may have accumulated.

Current Documentation

docs/code.claude.com/docs/en/troubleshoot-install.md line 807 covers env-var inheritance only for the credentials failure case:

If credentials work in your terminal but not in the VS Code or JetBrains extension, the IDE process likely didn't inherit your shell environment. Set the provider environment variables in the IDE's own settings, or launch the IDE from a terminal where they're already exported.

docs/code.claude.com/docs/en/env-vars.md line 137 documents the CLAUDECODE env var and the nested-session exclusion behavior, and line 197 documents the CLAUDE_CODE_FORCE_SESSION_PERSISTENCE override:

CLAUDECODE — Set to 1 in subprocesses Claude Code spawns (Bash and PowerShell tools, tmux sessions, hook commands, status line commands, stdio MCP server subprocesses). Use to detect when a script is running inside a subprocess spawned by Claude Code. A nested interactive claude TUI started this way, such as one driving the CLI in tmux, is automatically excluded from --resume, --continue, up-arrow history, and the claude agents list. Non-interactive claude -p sessions still persist. Set CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to override this exclusion

CLAUDE_CODE_FORCE_SESSION_PERSISTENCE — Set to 1 to force transcript persistence, prompt history, and claude agents registration even when this claude was launched from inside another Claude Code session. Use when an inherited CLAUDECODE value, for example from a tmux server first started by Claude Code, causes a genuine top-level session to be misclassified as nested

docs/code.claude.com/docs/en/sessions.md line 21 states that "Sessions are saved continuously to local transcript files as you work, so you can return to one after exiting or running /clear." — without exception for shells that inherit Claude Code env vars.

docs/code.claude.com/docs/en/vs-code.md line 357 states that "The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run claude --resume in the terminal. This opens an interactive picker where you can search for and select your conversation." — but does not warn that this was historically broken for the integrated terminal because the CLI inside it inherited CLAUDECODE=1 from the parent VS Code process.

What's Wrong or Missing?

A. The troubleshooting page has no entry for the transcript-not-saved symptom

A user whose session did not appear in claude --resume after running Claude Code inside the VS Code integrated terminal would search the troubleshooting page for "transcript" or "resume" and find no relevant entry. The closest guidance (line 807) addresses credentials, not sessions.

B. The "Resume a session" guarantee on the sessions page is unconditional

docs/code.claude.com/docs/en/sessions.md line 21 says "Sessions are saved continuously to local transcript files as you work" without acknowledging that, prior to v2.1.170, a claude TUI launched in the VS Code integrated terminal — or any shell that inherited Claude Code's CLAUDECODE=1 / CLAUDE_CODE_ENTRYPOINT env vars — was misclassified as a nested session and excluded from --resume, --continue, up-arrow history, and the claude agents list. Users running on v2.1.169 or earlier and reading this page would have no way to connect the symptom to the cause.

C. The v2.1.170 fix is undocumented

The release notes (https://github.com/anthropics/claude-code/releases/tag/v2.1.170) state:

Fixed sessions not saving transcripts (and not appearing in --resume) when launched from the VS Code integrated terminal or any shell that inherited Claude Code environment variables.

Nothing on code.claude.com mentions this fix. The CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 workaround documented at env-vars.md:197 is still useful as belt-and-suspenders, but it should now be presented as a workaround for older versions, not as the primary answer.

D. The VS Code page implies the CLI inside the integrated terminal shares history with the extension

docs/code.claude.com/docs/en/vs-code.md line 357 says "The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run claude --resume in the terminal." It does not flag that the integrated terminal historically inherited the parent VS Code's Claude Code env vars, which caused the CLI to silently fail to persist transcripts.

Suggested Improvement

Option A: Comprehensive fix (preferred)

Add a new troubleshooting entry to docs/code.claude.com/docs/en/troubleshoot-install.md under the appropriate section ("Authentication" or a new "Sessions" section):

Sessions launched from the VS Code integrated terminal or shells that inherit Claude Code env vars do not appear in --resume Fixed in v2.1.170. If you are on v2.1.169 or earlier and a claude session started in the VS Code integrated terminal — or any shell that inherited CLAUDECODE=1 or CLAUDE_CODE_ENTRYPOINT from a parent process — does not appear in claude --resume, the CLI was being misclassified as a nested session and excluded from transcript persistence. Workarounds for older versions: - Run claude in a fresh terminal that does not inherit Claude Code env vars (unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT before launching). - Set CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 in the environment of the integrated terminal. - Upgrade to v2.1.170 or later, which detects this scenario and persists transcripts normally. See Environment variables for the full list of Claude Code env vars and Manage sessions for how transcripts are stored.

Update the "Resume a session" section of docs/code.claude.com/docs/en/sessions.md to add a one-line note:

Sessions are saved continuously to local transcript files as you work, so you can return to one after exiting or running /clear. As of v2.1.170, this works even when the claude TUI is launched from a shell (such as the VS Code integrated terminal) that inherits Claude Code environment variables from a parent process; on older versions, use CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 as a workaround.

Update docs/code.claude.com/docs/en/vs-code.md line 357 to acknowledge the v2.1.170 fix:

The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run claude --resume in the terminal. (As of v2.1.170, this works correctly when claude is launched from the VS Code integrated terminal; on older versions, the integrated terminal inherits CLAUDECODE=1 from the parent process and the CLI session is excluded from --resume.)

Option B: Minimum fix

Add the single troubleshooting entry above and leave the other pages unchanged.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/troubleshoot-install | 807 | "If credentials work in your terminal but not in the VS Code or JetBrains extension…" — covers credentials only, no session/transcript entry |
| https://code.claude.com/docs/en/sessions | 21 | "Sessions are saved continuously to local transcript files as you work" — unconditional guarantee, no v2.1.170 note |
| https://code.claude.com/docs/en/vs-code | 357 | "The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run claude --resume in the terminal." — no caveat about the integrated-terminal / inherited-env-var history |
| https://code.claude.com/docs/en/env-vars | 137, 197 | Documents CLAUDECODE and the CLAUDE_CODE_FORCE_SESSION_PERSISTENCE workaround, but the workaround is presented as the primary fix, not as a v2.1.169-and-earlier fallback |

Total scope: 4 pages affected

Cross-references:

• Release notes for v2.1.170: https://github.com/anthropics/claude-code/releases/tag/v2.1.170
• CLAUDECODE env var: https://code.claude.com/docs/en/env-vars#clawdcode
• CLAUDE_CODE_FORCE_SESSION_PERSISTENCE env var: https://code.claude.com/docs/en/env-vars#clawde_code_force_session_persistence

Version notes:

• Bug present in v2.1.169 and earlier.
• Fixed in v2.1.170.
• The mechanism: an interactive claude TUI checks the CLAUDECODE env var on startup. If set to 1 (which the VS Code extension sets on its own process and which the integrated terminal therefore inherits), the TUI treats itself as a nested subprocess and skips transcript persistence. v2.1.170 detects the specific "started in an interactive terminal that is a child of an IDE process" case and persists transcripts anyway.