Plan Locally, Execute in the Cloud with Claude Code

Plan Locally, Execute in the Cloud: Claude Code's Own Recommended Workflow — a painterly illustration conveying this idea from "Plan Locally, Execute in the Cloud: Claude Code's Own Recommended Workflow"

The safest way to hand a big job to a Claude Code cloud session is to do the thinking on your own machine first. You agree on a plan with Claude where nothing can be changed, you save that plan into your project and push it to GitHub, and only then do you tell a cloud session to carry it out. This article walks through that sequence step by step so you can run it today, and explains the one detail that trips people up: the cloud session can only see what you have pushed.

If you are new to the idea that Claude Code can run somewhere other than your computer, start with the hub article, “Claude Code without your laptop”, which explains what a cloud session is and the five ways to reach one. This is the practical companion. If you have never used Claude Code at all, What Is Claude Code? comes first.

Why split the job in two?

A big change, such as migrating a project to a new framework or reorganising a messy folder of code, goes wrong in a predictable way. You describe the goal in one sentence, the assistant starts editing, and twenty minutes later you discover it understood the goal differently than you did. Now you have a pile of edits to untangle.

Splitting the work removes that risk. The first half is planning: you and Claude talk, Claude reads your files, and you agree on an approach. Nothing is edited. The second half is execution: a long, mostly hands-off stretch of work that does not need you watching. Planning needs your attention and your judgment. Execution mostly needs a computer that stays on. A cloud session is exactly that, a Claude Code session running on a computer that is not yours, so it keeps going when you close the lid.

Anthropic’s Claude Code documentation describes this sequence as its recommended way to work, and the commands below follow it. The documentation page is Claude Code on the web, which I checked on 2026-10-18. Despite the name, the browser is only one of several ways in. Here we use the terminal.

Step 1: Start Claude in plan mode

Open a terminal in your project folder and start Claude Code like this:

claude --permission-mode plan

Plan mode is a setting that lets Claude read your files and explore, but not edit your source code. It is the right mode for a conversation like “here is what I want, what would you change and in what order?” You can ask it to look at how the project is organised, find every place a particular tool is used, or list what a migration would touch.

Treat this as a real conversation, not a formality. Push back. Ask what could break. Ask it to put the riskiest step first, or to split the work into stages you can check one at a time. The quality of what the cloud session does later depends almost entirely on the quality of the plan you leave behind. A vague plan sent to a machine that works unattended is how you end up with a surprise.

A good plan has a few ingredients:

The goal, in plain words, including what “done” looks like.
The steps, in order, each small enough to check.
What must not change, such as files, folders or behaviour you want left alone.
How to tell it worked, for example “the test suite passes” or “the site still builds”.

Step 2: Save the plan inside the project

When you and Claude are happy, ask it to write the plan to a file in your repository. A path such as docs/migration-plan.md works well. A plain text or Markdown file is fine; it only has to be readable.

Saving the plan as a file, rather than leaving it in the chat, matters for a reason we will get to in a moment: the cloud session starts fresh. It does not remember your planning conversation. The file is how you pass the conversation across.

Plan mode will not let Claude write into your project on its own, so you will usually approve the step of saving the plan, or write the file yourself and paste in what Claude drafted. Either is fine. What counts is that the file exists in the project folder.

Step 3: Commit and push, and here is why

This is the step people skip, so it deserves a proper explanation.

Commit means saving a snapshot of your project’s files into git, the version-tracking system most code projects use. Push means sending that snapshot to GitHub, the website that hosts your project online. The copy on GitHub is called the remote.

git add docs/migration-plan.mdgit commit -m "Add migration plan"git push

Now the important part. When you start a cloud session, the computer that runs it does not reach into your laptop. It does not see your desktop or your open editor. Instead it clones your GitHub remote at your current branch, meaning it downloads a fresh copy of your project from GitHub, on whichever branch you were on when you launched it. It is not a copy of your local folder.

That one fact explains the whole step:

A plan you saved but never committed is not there. The cloud session cannot see it.
A plan you committed but never pushed is not there, either, because the commit exists only on your laptop.
Work on a different branch from the one you launched from is not there.

So “commit and push” is not bureaucracy. It is the delivery mechanism. The plan file reaches the cloud session by the same route as any other file: through GitHub. If you ever start a cloud session and it says it cannot find your plan, the first thing to check is whether the file was pushed.

The same logic is a quiet benefit. Because the session starts from a commit, you always know exactly what it started from, and you can throw its work away without having touched your own copy.

Step 4: Hand it to the cloud

With the plan pushed, start the cloud session from the same terminal:

claude --cloud "Execute the migration plan in docs/migration-plan.md"

The --cloud flag is what tells Claude Code to run this task on Anthropic’s infrastructure rather than your machine. Your instruction can be short precisely because the real detail lives in the plan file. You are saying “read the document we agreed on and do it.”

A few honest notes about this command:

--remote is an old name. You may find it in older tutorials. The documentation now describes --remote as a deprecated alias for --cloud. It still works, but use --cloud in anything new.
It is not the same as --remote-control. That one is unrelated: per the documentation, “--cloud creates cloud sessions. --remote-control is unrelated: it lets you monitor and steer a local CLI session from claude.ai or the Claude app.” The two are easy to mix up because of the word “remote”. I will say more about that in a separate article in this series on cloud, remote control and teleport.
It uses your plan’s usage allowance. There is no separate bill for the cloud computer, but the session draws on the same limits as the rest of your Claude use. A large unattended job is a large draw.

Once it is running, you can close the terminal, shut the laptop and go and do something else. You can check on the session from the Claude website or the mobile app.

Step 5 (optional): Nudge it while it works

Sometimes you want to add a thought after launching: “also skip the legacy folder” or “stop and tell me when the first stage is done.” You do not need to be at the original machine. From any computer where you are logged in to Claude Code, you can send a follow-up message into the running session:

claude -p "your message" --cloud <session-id>

The documentation’s form takes the session’s ID in place of <session-id>. Think of it as sending a text message to a worker who is already on the job.

What if my project is not on GitHub?

The method above assumes your project already lives on GitHub. If it does not, Claude Code has a fallback: it can bundle your local repository into a single file and upload it. A bundle is a packed-up copy of your git history made with a standard git feature (the git project documents it as git bundle).

The documentation lists the conditions for this route:

The folder must be a git repository with at least one commit.
The bundle must be under 100 MB.
Untracked files are not included. If a file was never added to git, it does not travel.
On macOS, Linux and WSL (Windows Subsystem for Linux), you need git 2.31 or later.

You can force this route, even when you do have a GitHub remote, by setting the environment variable CCR_FORCE_BUNDLE=1 before you launch. Most people never need it. If your project is on GitHub, the normal clone route is simpler.

Notice that the fallback follows the same principle as the main route: the cloud session sees committed work. Whichever way the project travels, a file that git does not know about does not arrive, so the commit step still applies.

A caution before you press enter

Planning locally has a second benefit that is easy to overlook: you get a calm moment to decide what you are about to send. Two things from the documentation are worth keeping in mind.

First, a cloud session is not purely sealed off, even with its network access disabled. Anthropic’s documentation says: “When running with network access disabled, Claude Code can still communicate with the Anthropic API, which may allow data to exit the VM.” (A VM, or virtual machine, is the temporary computer your session runs on.) Do not put anything in your plan or your project that you would not be comfortable having processed by Anthropic’s service.

Second, if you use native Windows, read the documentation’s note about uncommitted changes before you launch. It says that on native Windows, “uncommitted changes to tracked files upload as they are, whatever the file’s name. Stash or revert an edit you don’t want in the cloud session before you start it.” On macOS, Linux and WSL, files named like credentials or keys are left out of the upload, but that protection is described as not applying on native Windows. Our separate article on cloud session security covers this in detail. For this workflow, the practical habit is simple: before you launch, run git status, look at what is changed, and make sure nothing sensitive is sitting in there.

The whole workflow on one page

claude --permission-mode plan, then agree on the approach with Claude, with no edits happening.
Save the plan to a file in your project, for example docs/migration-plan.md.
git add, git commit and git push, so the plan is on GitHub.
claude --cloud "Execute the migration plan in docs/migration-plan.md".
Check progress from the web or mobile app, and send follow-ups with claude -p "..." --cloud <session-id> if needed.

The same habit that makes this work, planning where it is cheap and executing where it is hands-off, also keeps you in control. You decide the destination while you are present and attentive, and the cloud session does the long walk. The commit and push in the middle is the handoff: the moment your decisions become something another computer can read.

For the bigger picture of what cloud sessions are, how they differ from the terminal sessions you already know, and where else you can start one, read the hub, “Claude Code without your laptop”.

Frequently Asked Questions

Why can’t the cloud session see the change I just made? Because it never looked at your computer. The cloud VM clones your current directory’s GitHub remote at your current branch — not your local checkout. Anything you have not committed and pushed simply is not there. This is the single most common source of “why is Claude working on the old version?”, and the reason the commit-and-push step in this workflow is not bureaucracy.

Does plan mode change my files? No. In plan mode Claude reads files and runs commands to explore, and proposes an approach without editing source code. That is what makes it safe to iterate on the plan before any work begins.

What if my project isn’t on GitHub at all? Claude Code bundles your local repository and uploads it instead. The limits are worth knowing: the directory must be a git repository with at least one commit, the bundle must be under 100 MB, untracked files are not included (run git add first), and on macOS, Linux and WSL you need git 2.31 or later. A session created from a bundle can only push back to a GitHub remote your connection already has push access to.

Can I send instructions to a session after it has started? Yes, from any machine where you are logged in: claude -p "your message" --cloud <session-id>. The command queues one message into the session and exits, so it works from a second computer or a CI script.

Sources: Anthropic, Claude Code on the web, checked 2026-10-18; git project, git bundle documentation. Flags and limits in cloud features change often; check the documentation for the current state before relying on them.

📦 Recommended Resources

Some links below are Amazon affiliate links. If you buy through them we earn a small commission at no extra cost to you.

The free material is the right starting point here. Anthropic’s Use Claude Code in the cloud page documents the plan-locally workflow in its own words, including the sentence this whole article hangs on — that the cloud VM clones your remote at your current branch, not your local checkout. The git bundle documentation is worth a skim if you work on projects without a GitHub remote, because it explains the mechanism behind the upload fallback.

The three books below are for the workflow habits this article depends on.

Pro Git by Scott Chacon and Ben Straub — if any single book makes this workflow click, it is this one. The commit-and-push step only feels like bureaucracy until you have a clear mental model of what a remote is and what “pushed” actually means; after that it feels like saving your work. Chapters 2 and 3 are enough. Also free in full at git-scm.com/book.

Version Control with Git by Prem Kumar Ponuthorai and Jon Loeliger (3rd edition) — the more thorough companion to Pro Git, and the better choice if you want to understand why git behaves as it does rather than which commands to type. Useful here specifically for its treatment of branches and remote-tracking, which is the exact area where “why can’t the cloud session see my change?” lives.

Continuous Delivery by Jez Humble and David Farley — the book that argued, long before agents existed, that the repository should be the single source of truth for what gets built. Plan-locally-execute-in-cloud is a small instance of that principle: the plan goes into the repo and gets committed precisely so that something other than your laptop can act on it. Dated in its tooling, undated in its reasoning.

✅ Pro tip: Commit the plan as its own commit, with a message that says it is a plan — docs: migration plan for the auth refactor, not wip. You get three things for free: the cloud session can be pointed at a specific file, the diff it later produces can be read against the plan it was given, and six weeks later you can see what you actually asked for rather than reconstructing it from the result.