Launching Claude Code
Overview
Launch Claude Code is a one-click way to start Claude Code already wired to a board. The primary button — labelled "Launch Claude Code" in the board toolbar — fires a claude-cli:// deep link that opens Claude Code, connects the VibeCodes MCP server, and offers you the next task on the board.
Instead of copying commands and explaining context by hand, one click hands Claude Code everything it needs: which project to open, how to connect, and what's waiting on your board.
Where You Can Launch From
There are several entry points throughout the app — wherever you are, launching Claude Code is close at hand:
- Board toolbar — a split button: "Launch Claude Code" plus a chevron that opens the "Launch options" dropdown
- Task card menu — "Launch in Claude Code"
- Task detail header — a terminal icon labelled "Launch in Claude Code"
- MCP connection banner
- Dashboard setup checklist
- Onboarding
The Launch Options Dropdown
The chevron next to the launch button opens a menu of options:
- "Open in Claude Code" — the standard launch
- "This machine" — a line showing the saved folder path when one is set
- "Start a new project…"
- "Copy launch command"
- "Set exact folder (advanced)…"
- "Install guide" — links to docs.claude.com/en/docs/claude-code
Running It In The Browser — Multiple Sessions at Once
Picking "In the browser" (Beta) from the Launch options dropdown opens a live terminal docked to the bottom of the board, mirroring Claude Code running on your own machine through the VibeCodes helper — your code never leaves your computer.
You're not limited to one session at a time. You can run several sessions concurrently — any mix of terminal windows and in-browser tabs — each working on its own task:
- Tabs in the dock — every launch (toolbar, task card, or the dock's "+") opens a new tab rather than replacing what's already running. The dock shows how many in-browser sessions you can have running at once, and explains what to do if you're at that limit.
- Automatic worktree isolation — your second and later concurrent sessions on the same repo each get their own private git worktree (a sibling
<repo>.vibe/wt-1,wt-2, and so on, each on its own branch) so two sessions never collide editing the same files. Your first/primary session keeps working in the repo folder itself, unchanged. - My sessions — the dock's "My sessions" button lists every session running across all your ideas, with a one-click End per session and an "End all sessions" panic button for when you just want everything stopped.
- Pop-out — any in-browser session can be popped into its own browser window (the tab's "Pop out" button). It's the exact same session, just in different glass: closing the popped-out window brings it back to the dock automatically, or use "Bring back to dock" from the dock's tab at any time.
Each session runs a real Claude Code process on your computer — running several at once uses more of your machine's resources. Close sessions you're done with rather than leaving them running indefinitely.
What the Launch Actually Does
The launch generates a prompt that tells Claude Code to do four things, in order:
- Move into the project directory
- Connect the
vibecodesMCP server via Claude Code's built-in/mcpsign-in flow — a human-in-the-loop OAuth handshake. It does not hand-build URLs. - Record the project folder so future launches reopen it automatically
- Pick up board work
A board launch reads the board, tells you which unstarted task is next up, and asks whether you want it — so you can say yes, or point the session at something else entirely (a bug you just spotted, work you left half-finished). Say yes and it assigns the task to you, moves it to In Progress, and if the task has a workflow it uses claim_next_step. Launching from a specific task skips the question and goes straight to that task.
Existing Folder vs New Project
How Claude Code chooses where to work depends on your idea:
- If the idea has a GitHub repo — Claude Code opens or clones that repo automatically
- If the idea has no repo — use "Start a new project…". The dialog (titled "Start a new project") lets you set a "New folder name" and pick where to "Create it inside" (defaults to
~/projects). Claude Code runsgit init(orgit cloneif a repo exists) when it launches. - "Set exact folder (advanced)…" — point Claude Code at an existing absolute path
Important: the path must be a fully-expanded absolute path — ~ and $HOME are not supported. Tip: in your terminal, cd to the folder and run pwd — that prints the exact path to paste here.
Privacy of Your Folder Path
The folder path you save is private to you. As the app states:
"Stored on this device only — never shown to other collaborators."
The path is saved in your browser's localStorage, per machine — so the "This machine" line in the dropdown only ever reflects the device you are on.
Copy-Command Fallback
Deep links are convenient but not bulletproof — the claude-cli:// link can be blocked by the browser, or silently ignored if the generated OS URL is too long.
When that happens, use "Copy launch command". It copies the full command — you'll see the toast "Launch command copied — paste it in your terminal" — and you paste it straight into your terminal. The copy fallback always works and carries the full instructions, so reach for it any time the deep link doesn't open.
Troubleshooting
Terminal shows "model not found" as soon as the session starts — your starting-model setting names a model Claude Code doesn't recognise. Fix it in Profile → Model Tiers (or ask an admin to check the platform default on the admin Platform tab), then start a fresh session. Resumed sessions aren't affected — they keep the model they were already running on.
Desktop Only
The claude-cli:// scheme only works on desktop where Claude Code is installed. On mobile the option is disabled and shows "Open on desktop to launch Claude Code".
You need Claude Code installed first. See the MCP Integration guide for install and connection details.
Related Guides
To understand the underlying MCP connection that the launch sets up, read the MCP Integration guide → And to learn what happens when the picked-up task has a workflow, see the Workflows guide →