[DOCS] Inconsistent terminology regarding "Moving" vs. "One-way handoff" for Web/Terminal tasks

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/claude-code-on-the-web#moving-tasks-between-web-and-terminal

Section/Topic

The "Moving tasks between web and terminal" section and its subsequent note on session handoff.

Current Documentation

The documentation states:

"You can move between local and remote development: send tasks from your terminal to run on the web with the & prefix, or teleport web sessions back to your terminal to continue locally."

It then follows with a Note:

"Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web. The & prefix creates a new web session with your current conversation context."

What's Wrong or Missing?

There is a logical inconsistency in using the phrase "move between" alongside "handoff is one-way."

• The introductory text implies a bidirectional "move" capability.
• The note clarifies that you cannot actually "move" or "push" an active terminal session to the web; you can only initiate a new session that clones the current context.
• This creates confusion for users who might expect their active terminal state (including uncommitted local changes or specific environmental state not captured in the context clone) to migrate to the cloud.

Suggested Improvement

The section should clearly distinguish between Context Cloning (Terminal to Web) and True Handoff/Teleporting (Web to Terminal).

Suggested Text Adjustment:
Change the section header or introductory sentence to:
"Transitioning between local and remote development"

Clarify the & prefix behavior:
"You can initiate remote execution from your terminal by using the & prefix to create a new web session based on your current context. To migrate an active session, use the teleport feature to pull web sessions into your local terminal."

Update the Note to be more explicit:
"Note: Session state migration is one-way (Web to CLI). Using the & prefix in the terminal does not 'upload' your current local session; it creates a separate, new remote session containing a snapshot of your current conversation context."

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation on session management: https://platform.claude.com/docs/en/agent-sdk/sessions
• Documentation on the & prefix: https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-web

[coygeek]

Thank you for the updates to the documentation. I have reviewed the current content at https://code.claude.com/docs/en/claude-code-on-the-web against my original report regarding the inconsistencies in session handoff descriptions.

What’s FIXED

• Explicit Directionality Note: A crucial note has been added to the "Moving tasks between web and terminal" section at https://code.claude.com/docs/en/claude-code-on-the-web#moving-tasks-between-web-and-terminal. It now explicitly states: "Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web."
• Context Cloning Clarification: In the "From terminal to web" subsection (https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-web), the text now correctly defines the & prefix behavior, stating that it "creates a new web session on claude.ai with your current conversation context." This replaces the previous ambiguity about whether an active session was being migrated.
• Teleportation Requirements: The addition of the "Requirements for teleporting" table at https://code.claude.com/docs/en/claude-code-on-the-web#requirements-for-teleporting provides necessary technical precision regarding git state and repository ownership that was missing previously.

What’s UNRESOLVED

• Linguistic Inconsistency in Intro/Header: Despite the corrective note, the primary introductory sentence still reads: "You can move between local and remote development..." Furthermore, the section header remains "Moving tasks between web and terminal." As noted in the original issue, the word "move" (and "between") strongly implies a bidirectional or reversible capability.
• Snapshot vs. Migration: While the documentation clarifies that & creates a "new session," it still lacks a specific warning that environmental state or uncommitted changes not explicitly in the "conversation context" will not be present in the new cloud session. Using the term "snapshot" as suggested would help clarify that this is a point-in-time clone rather than a stateful migration.
• Terminology Conflict: There is still a slight conflict between the header's "Moving tasks" and the Note's "Session handoff is one-way." If the handoff is one-way, "Moving" is technically inaccurate for the Terminal -> Web flow.

Conclusion

The documentation is significantly improved and much less likely to lead to data-loss assumptions than the previous version. However, because the high-level headers and introductory phrasing still use the potentially misleading "move between" terminology, I am keeping this issue open.

To fully resolve this, I recommend updating the section header to "Transitioning between local and remote development" and the introductory sentence to state that users can "initiate remote tasks or pull web sessions back to the terminal," avoiding the implication of a bidirectional "move" of a single active session.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

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.