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 starts working 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 which task to pick up first.
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
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, takes the top unstarted task, assigns it, moves it to In Progress, and if the task has a workflow it uses claim_next_step. Launching from a specific task targets that task instead of picking the top one.
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.
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 →