[DOCS] `claude --cloud` bundles local repo state even when GitHub can serve the branch — documented clone behavior and "push first" guidance do not match observed behavior

Summary

The Claude Code on the web docs describe claude --cloud as cloning your GitHub remote, with local-repo bundling as a narrow fallback for repositories that aren't on GitHub. In testing, the cloud session received local repository state in every case I could distinguish — including when the branch exists on the remote and the local checkout is merely ahead by one commit.

The documented contents of a bundle are accurate. The trigger condition and the user guidance derived from it are not.

Relation to #81776

#81776 reports the same observable (claude --cloud producing bundle sessions when GitHub auth is configured) and treats it as a CLI handshake bug, on the premise that the documented clone behavior is correct.

My results are consistent with that report's observation but I can't tell which side is authoritative:

• If bundling is intended, the docs are stale and should be corrected (this issue).
• If bundling is a regression, #81776 is the bug and the docs are right.

Either way one of the two is wrong today, and the two reports together should help triage. I'm filing this separately because the docs-accuracy fix is needed under the first reading and is not covered by #81776's framing.

Note that #81776 observed bundling even on main fully in sync with origin, which is the one case my tests could not distinguish (identical content either way).

Statements that don't match observed behavior

1. From terminal to web:

The cloud VM clones your current directory's GitHub remote at your current branch, not your local checkout, so push first if you have local commits.

Local commits reached the cloud session without being pushed. The "push first" instruction asks for unnecessary work.

2. Send local repositories without GitHub:

When you run claude --cloud from a repository that isn't connected to GitHub, Claude Code bundles your local repository and uploads it directly to the cloud session. This fallback activates automatically when GitHub access isn't available.

Bundling also occurred when the repository was connected to GitHub and GitHub access was available.

Reproduction

Environment: Claude Code 2.1.228, macOS 14.5, git 2.47.0, claude.ai subscription, GitHub connected via the Claude GitHub App, repo has a normal origin remote on github.com.

mkdir test && cd test
echo "# test" >> README.md
git init && git add README.md && git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/<you>/test.git
git push -u origin main

Case A — branch not on the remote

git checkout -b test-branch
echo "# test2" >> README2.md
git add -A && git commit -m "test commit"
claude --cloud "Run these and paste raw output: git log --oneline -5; ls -la"

git ls-remote origin confirms the remote has only refs/heads/main. Cloud session:

07fab7e test commit          <- exists only on my machine
ab1741b first commit

README2.md present.

Case B — branch on the remote, local ahead by one commit

git push -u origin test-branch          # remote now at 07fab7e
echo "ahead" > AHEAD.md
git add AHEAD.md && git commit -m "local commit ahead of origin"
claude --cloud "Run these and paste raw output: git log --oneline -5; ls -la"

Local: ## test-branch...origin/test-branch [ahead 1]. Remote (git ls-remote origin) still at 07fab7e. Cloud session:

15a9808 local commit ahead of origin   <- not on the remote
07fab7e test commit
ab1741b first commit

AHEAD.md present. This is precisely the case the "push first if you have local commits" guidance addresses.

Case C — bundle contents (docs are accurate here)

echo "dirty edit" >> README.md        # tracked, uncommitted
echo "untracked" > UNTRACKED.md       # untracked
claude --cloud "Run these and paste raw output: git status --short; cat README.md; ls -la"

Cloud session:

 M README.md

# test
dirty edit

UNTRACKED.md absent. The uncommitted modification transfers and is preserved as uncommitted; untracked files are excluded. Both match the documented bundle contents.

Documented vs. observed

| | Documented | Observed |
|---|---|---|
| Repo not on GitHub | bundle | bundle ✅ |
| Branch not pushed | clone remote | bundle ❌ |
| Branch pushed, local ahead | clone remote | bundle ❌ |
| Local commits | lost unless pushed | transferred ❌ |
| Uncommitted tracked changes | in bundle | in bundle ✅ |
| Untracked files | excluded | excluded ✅ |

Why this matters

Under the "docs are stale" reading, the page misleads in both directions:

• It prescribes an unnecessary git push before every --cloud invocation.
• It obscures the one behavior that genuinely drops data silently: untracked files are excluded with no warning. A newly created file that hasn't been git added doesn't exist in the cloud session, and the agent works around or recreates it. The habit users actually need is git add, not git push — the opposite of what the page emphasizes.

Suggested fix (if bundling is intended)

State the trigger in terms of what the cloud can obtain, e.g. "Claude Code uploads your local repository state whenever the cloud can't obtain your current branch from GitHub — including a branch you haven't pushed, or local commits ahead of the remote." Remove or correct the "push first if you have local commits" instruction, and give untracked-file exclusion more prominence.

#81776's second ask is also worth adopting regardless of which reading wins: have --cloud state which mode it chose ("cloning from GitHub" vs "uploading a bundle") at session creation. The session link looks identical either way, which is what makes this hard to reason about from the outside.

Question

What does CCR_FORCE_BUNDLE=1 override in current builds? The env-vars reference describes it as forcing bundling "even when GitHub access is available", but I could not observe a default clone path for it to override.