Claude Code Ultraplan: What the Docs Don’t Tell You
Write less code by writing better plans
You ask Claude to build a feature. It writes 200 lines of clean, well-structured code. Then you realize it picked the wrong API pattern, missed a constraint you mentioned two prompts ago, and built against a table you deprecated last month.
You delete everything. Start over. More context this time.
Same category of mistake. Different details.
This is the most expensive part of AI-assisted coding. Not the token cost — the time you spend on code that solves the wrong problem. One developer tracked this for a month: direct-to-code prompting vs. planning first, then executing. The planning approach was 40% faster. Not because the coding was faster. Because the rework disappeared.
Ultraplan is Claude Code’s attempt to fix this. It creates a dedicated space where you and Claude align on what to build before either of you writes a line. Cloud-based planning, browser-based review, then you choose where to execute.
The docs cover the basics fine. This article covers everything else — the workflow that makes it worth using, the hidden planning engines most people don’t know about, and the specific situations where you should skip it entirely.
The 60-Second Version
Type /ultraplan plus your task. Claude spins up Opus 4.6 in Anthropic’s cloud for up to 30 minutes of planning. Your terminal stays free — you keep working while a status indicator tracks progress.
When the plan is ready, you review it in your browser. Inline comments on specific sections. Reactions. An outline sidebar. It’s a real review surface — not a terminal wall of text you skim and approve.
After review, two choices: execute in the cloud (Claude implements and opens a PR) or teleport the plan back to your terminal for local execution.
That’s the feature. Now here’s what actually matters.
Write Specs, Not Tasks
The single biggest factor in plan quality is your initial prompt. Most people write task descriptions. Write specs instead.
This produces a generic plan:
/ultraplan add rate limiting to the APIThis produces a plan you’d actually execute:
/ultraplan add rate limiting to /api/search and /api/export.
Use sliding window counter in Redis (existing instance at
src/lib/redis.ts). Limit: 100 req/min per API key.
Return 429 with Retry-After header when exceeded.
Don't touch /api/health or /api/auth.
Key files: src/api/routes/, src/middleware/.
Stack: Express 4 + TypeScript.The difference isn’t length. It’s precision.
The first prompt forces Claude to guess your stack, your constraints, and your boundaries. It’ll spend 10 minutes exploring your codebase to figure out things you already know. The second prompt lets Claude use its 30 minutes on actual planning instead of archaeology.
Three rules for specs that produce good plans:
Include file paths. Always. The cloud session starts from scratch. Every path you provide is time Claude doesn’t waste searching.
State constraints explicitly. “Don’t touch X” is more useful than “focus on Y.” Boundaries prevent the plan from sprawling.
Name your stack. Framework, language, database, key libraries. Claude can infer these from your code, but inference takes time and sometimes gets it wrong.
Think of it this way: you’re briefing a skilled contractor who’s never seen your codebase. What would they need to know before drawing up a plan?
Start Local, Promote to Cloud
Don’t start every task in Ultraplan. Start in local plan mode.
Local plan mode is faster. You get a rough plan in minutes, and you can course-correct in real-time: “No, use the existing adapter pattern.” “Skip that — we already have that middleware.” Quick terminal back-and-forth.
Once the direction is right but the plan needs depth — promote it to the cloud. When Claude shows the local plan approval dialog, choose “refine with Ultraplan on Claude Code on the web.” The local context carries forward. The cloud session deepens it.
This is consistently how I get the best Ultraplan results. Local for direction. Cloud for depth.
When to skip local and go straight to Ultraplan:
The task is complex enough that you want Claude to explore the codebase broadly before proposing anything
You need architectural diagrams or risk analysis in the plan
You want to hand off the planning and do other work in your terminal
When to stay local entirely:
You can describe the change in one or two sentences
You need rapid iteration — terminal conversation is faster than browser comments for tight feedback loops
Your workflow depends on local MCP servers, custom tools, or configs that don’t transfer to the cloud
Comment Like a Code Reviewer
The browser review surface is powerful. Most people waste it.
After Ultraplan finishes your plan, you open it in the browser and can leave inline comments on any section. Claude revises based on your feedback. You can go back and forth as many times as you need.
The difference between a useless review and a transformative one is the same as code review: specificity.
Comments that produce nothing:
“Make this section better”
“Can you add more detail?”
“I’m not sure about this approach”
Comments that produce great revisions:
“This assumes a Redis connection pool. We use single connections via ioredis. Adjust the caching strategy.”
“Wrong migration order. Users table has a FK to sessions — sessions migration runs first.”
“Add rollback steps for phases 3-5. If JWT migration fails mid-deploy, what’s the revert path?”
“This plan doesn’t account for the background job worker in src/workers/. It reads from the sessions table directly.”
Each comment should be specific enough that Claude can revise without asking a follow-up. Point out what’s wrong AND what right looks like.
Pro tip: After your first round of comments, add one global comment: “Flag anything in this plan you’re uncertain about.” This primes Claude to surface its own assumptions instead of presenting everything with equal confidence. The flagged items are usually where the real risks hide.
The Hidden Variants (Why Your Experience Differs From Everyone Else’s)
Here’s the part that should probably be in the docs but isn’t.
Leaked source code from Claude Code’s NPM registry revealed Ultraplan runs three completely different planning engines. Which one you get is assigned by server-side A/B testing. No UI to select. No indicator showing which one you received.
simple_plan — Lightweight exploration, mirrors local plan mode. You get an ordered list of changes with file references. Adequate for focused tasks. Not what makes Ultraplan worth leaving the terminal for.
How to spot it: Plan is short, bulleted, reads like quick notes. No diagrams. No self-critique.
visual_plan — Same exploration plus Mermaid and ASCII architecture diagrams. Shows before-and-after structural changes visually. Dependency graphs that make circular references obvious. Data flow maps that reveal where a service boundary actually needs to go.
How to spot it: Diagrams in your plan. That’s the tell.
three_subagents_with_critique — The one worth getting.
Three parallel research agents independently analyze your codebase. Findings get synthesized into a unified plan. Then a critique phase argues against the plan’s own recommendations — surfacing risks, edge cases, and alternatives the other variants miss entirely.
How to spot it: The plan has a “considerations” or “risks” section that challenges its own suggestions. It reads like three people reviewed the problem.
The practical impact: Someone who got three_subagents_with_critique will rave about Ultraplan. Someone who got simple_plan for a complex task will think it’s barely better than local mode.
What to do about it: If your plan feels thin for the complexity of the task, reject and re-run. Relaunching sometimes assigns a different variant. Not guaranteed — but it’s your only lever until Anthropic adds variant selection or at least tells you which one you’re running.
Steal These Prompts
Five /ultraplan prompts for the most common scenarios. Copy, paste, fill in the brackets.
The pattern behind all of them: task + file paths + constraints + desired output format.
Migration:
/ultraplan migrate [service] from [current] to [target].
Key files: [paths]. Current dependencies: [list].
Constraints: zero downtime, backward compatible during transition.
Include rollback plan for each step.
Flag anything you're uncertain about.Refactor:
/ultraplan refactor [module/dir] to [target pattern].
Current state: [describe what exists]. Problem: [why refactoring].
Must not break: [public APIs/contracts].
Suggest logical PR split points for reviewability.
Flag anything you're uncertain about.New feature:
/ultraplan implement [feature description].
Integrates with: [existing systems]. User sees: [expected behavior].
Known edge cases: [list them].
Include test strategy with specific test cases.
Flag anything you're uncertain about.Architecture review:
/ultraplan review architecture of [system/module].
Analyze: performance bottlenecks, error handling gaps,
scaling limits, coupling between [components].
Recommend changes with effort/risk estimate for each.
Flag anything you're uncertain about.Bug investigation:
/ultraplan investigate [bug description].
Repro steps: [steps]. Expected: [X]. Actual: [Y].
Suspect areas: [files/modules].
Map all code paths that could cause this.
Rank fix options by risk and effort.
Flag anything you're uncertain about.Notice every prompt ends with “flag anything you’re uncertain about.” This one line consistently improves plan quality more than any other trick I’ve found. It turns Claude from a confident presenter into an honest collaborator.
Match Execution to Task Type
After approving the plan, you choose: cloud execution or teleport to terminal. This decision matters more than people think.
Execute in the cloud when:
The change is self-contained — pure code, no local infra dependencies
You want a PR opened automatically
You don’t need local test suites, env vars, or custom tooling during implementation
Teleport to terminal when:
You need local MCP servers, databases, or custom scripts
You want to run tests as you go
The plan references infrastructure that only exists on your machine
You want to inject the plan into an ongoing conversation where Claude already has context
The cloud environment blind spot: Your local .claude/ configs, MCP servers, and uncommitted changes don’t transfer to the cloud session. The docs are vague on this — they say you get your “default cloud environment.” In practice, that means your GitHub repo and Anthropic’s default tooling. Nothing custom.
If your plan depends on local tools, execute locally. If you execute in the cloud and the plan references local infrastructure, Claude will either skip those steps or make assumptions. Neither outcome is what you want.
The Friction You Should Know About
Three things that catch people off guard.
It’s slower than local plan mode. The cloud round-trip adds real time — session spin-up, repo sync, 3-second polling interval, browser context switch, revision cycles. For complex architectural work, the thoroughness is worth it. For a quick feature, it’s overhead. My threshold: if the plan would take longer than the implementation, stay local.
Remote Control disconnects. If you use Claude Code’s Remote Control feature, launching Ultraplan kills it. Both occupy the same claude.ai interface. Only one can be active. Save your Remote Control state before launching if you use both.
File sync is opaque. How your codebase reaches the cloud isn’t documented well. Users consistently report confusion about what the cloud session can see. The safe bet: commit your changes to Git before launching Ultraplan. If it’s not committed, assume the cloud session doesn’t have it.
When to Skip Ultraplan Entirely
Simple tasks. One-sentence changes don’t need 30-minute cloud plans.
No GitHub repo. Hard requirement. No workaround.
Heavy local tool dependencies. MCP servers, custom scripts, local databases — none transfer.
Speed matters more than thoroughness. Local plan mode starts instantly.
You want conversation, not comments. Terminal back-and-forth is faster for quick iteration than browser inline comments.
The rule I use: If the task makes me nervous — migration, shared code, cross-cutting concerns, anything where a missed dependency costs hours — Ultraplan. Everything else stays local.
Why This Matters Beyond the Feature
Ultraplan is the first shipped piece of something larger. Leaked source code shows features that haven’t launched yet — persistent cross-session memory, background agent processes, multi-agent coordinators. Cloud-based planning is the opening move.
But the real takeaway isn’t about Anthropic’s roadmap.
It’s that planning is the highest-leverage step in AI-assisted coding, and almost nobody invests in it. The data backs this up: planning-first is 40% faster. Unguided coding succeeds about a third of the time. Roughly 90% of Claude Code’s own codebase was written by Claude Code — but with engineers driving the planning at every step.
Ultraplan makes the planning step hard to skip. That’s its actual value.
Next time you’re about to ask Claude to implement something complex, put /ultraplan in front of it. Write a spec, not a task. Review the plan like you’d review a PR. Catch the wrong assumptions before they become wrong code.
Worst case: 10 minutes. Best case: you stop throwing away code.