Hand off a branch to Claude Code

Why hand off from Leefy instead of pasting into chat?

Chat tabs forget. Claude Code sessions without names blur together. Leefy attaches one named session to one node: the plan, soil, and scope ride along, and you can resume the same session later instead of starting “continue 9”.

About five minutes once Claude Code is installed. Leefy generates the prompt; Claude Code does the building.

What do I need before I start?

• A Leefy tree with at least one node that is ready to build (clear title; enough description or tasks that you trust the scope).
• Claude Code installed and signed in on your machine (or access to claude.ai/code for a browser session).
• Optional: a local project folder and a GitHub repo if you want commits and deploy later.
• Enough Anthropic access for Claude Code itself (that is your Claude / Anthropic subscription — separate from Leefy credits and from BYOK keys in Leefy).

How do I start a session from a node?

1. Open your tree in Leefy and select the node you want built (or open its work stream).
2. Open Code mode on that node — from the node pin Code, the context menu grow actions, or the stream Grow ▾ → Code.
3. Generate a code prompt if one is not already there. Wait until generation finishes (the panel should show the full prompt, not a spinner).
4. Create a Claude Code session — use the primary control on the prompt panel (Create Claude Code session / equivalent). Leefy records a named session on that node (WBS + title based).
5. Start work using one of the three handoffs Leefy offers (pick what your machine supports):

Option A — Terminal command (most reliable)

1. Copy the claude -n "session-name" "…" command from the session card or prompt panel.
2. Open Terminal, cd into your project folder if you have one.
3. Paste and run the command. Claude Code starts a named session.

Resume later with the resume command Leefy shows (typically claude --resume "session-name").

Option B — Deep link (macOS with Claude Code installed)

1. Click the deep-link control on the session if it is enabled.
2. Claude Code should open with the prompt pre-filled. If the link is disabled because the prompt is too long, use Option A instead — that is intentional, not a failure.

Option C — Browser (claude.ai/code)

1. Open the web handoff link from the session if shown.
2. Confirm the prompt is prefilled. Browser sessions are fine for exploration; named local sessions are better for long implementation work.

You’re done starting when Claude Code is running against that scope and Leefy’s session row exists on the node (status planned or running).

What context does Claude Code get?

Depending on your tree setup, the generated prompt packages:

• The focused node (title, description, tasks / definition of done).
• Ancestry and siblings so scope stays honest (what is in vs out).
• Soil / bedrock docs you enabled for code-style actions — decisions that should survive between sessions.

You should still read the prompt once before a large run. If something is wrong, edit the node description or soil and regenerate — do not silently trust a stale package.

When should I use Claude Code Plan mode?

Leefy holds the product plan (what to build, why, out of scope). Claude’s Plan mode is a session plan — how to implement this handoff right now.

Start a plan handoff from Leefy: Grow ▾ → Plan (or the context menu). That generates a plan-only prompt, creates a named session with a plan return contract (leefy-plan-summary), and asks the agent not to write application code. Use Grow ▾ → Code when you want an implement session instead.

Step-scoped Code sessions: When a task step is ready (no blocked deps / amber inputs), open it in the work stream and click Code session. That creates a named handoff for that step only, lands Resume on it, and after you harvest you can Mark step done & advance so the bouncing ball moves to the next ready step.

Plan queue (multi-slice branches): When you Accept plan with Branches to grow, those siblings form an ordered Plan queue in the work stream. Status dots show pending / in progress / done / later. When a slice is finished and no step pointer is active, the next slice pill offers the following incomplete sibling — so multi-feature plans stay guided end to end.

Plan sessions author the brief, not just the branches. A plan session with repo access writes a short brief (goal, acceptance criteria, scope, key files it actually opened) and a run-with recommendation for each slice. Accept plan stores that brief as the slice's description and the run-with as its metadata — so the Code prompt for an accepted slice assembles instantly from what the plan session already found, no extra AI call.

Use Plan mode first when:

• The node is large or still fuzzy (e.g. “auth system” without sub-branches).
• You’re in a brownfield repo and need an exploration plan before writing code.
• The slice is architecture-sensitive and you want a reviewable approach before build.
• A previous implement session got stuck and you need to re-scope before burning another run.

Skip Plan mode and implement when: scope, soil decisions, and definition of done are already clear on the node.

Plan mode does not replace Leefy’s tree, coach, or grow actions. It is a tool inside a named session that started from the tree. When Plan mode proposes several slices, harvest the plan summary and use Bank & accept plan to grow checked branches, plant a task for steps on a leaf, lock decisions onto the node, and park later items — uncheck anything you want left as a log only.

How do I bring results back to Leefy?

Claude Code does not write your tree for you. After a useful stretch of work:

1. In Leefy, open the session on that node.
2. Update status (running → done, or stuck if blocked).
3. Paste a short harvest into session notes or the node: what shipped, what broke, what is next. Prefer the fenced Leefy Session Summary block from the prompt’s return contract when present — Harvest can parse it.
4. Optionally produce or edit artifacts on the node so the deliverable lives in the garden, not only in the repo.
5. If the branch is shippable, mark progress toward fruit / harvest in your normal tree workflow — still no automatic “deployed” flag.

If the session was a plan (not implement): paste the leefy-plan-summary block. Review the checkboxes (branches / steps / decisions / later), then Bank & accept plan. Branches grow as children; steps become a task only while the node stays a leaf. Prefer one recommended Code session at a time on the ready slice afterward.

If the session kept going after its summary: the implement contract tells the agent to send an add-on summary — same block, marked covers: since-last-summary, covering only the new work. Harvest labels it, so you are not re-offered items you already planted. Type Full Leefy summary to the coding agent when you would rather have one complete summary of the whole session; it supersedes the add-ons. Plan sessions work the other way: a changed plan is re-sent whole, because Accept plan takes the slices as a set.

Premise check: an implement return contract closes with a Premise check — which of the brief's claims about the repo held (ok:) and which did not (false:). Harvest surfaces false premises so you see where the brief was wrong instead of silently getting different work than you asked for.

You’re done when the next person (including you next week) can open the node, see the session name, and know where the code and the leftover work live.

How do I resume instead of starting over?

1. Open the same node’s session list.
2. Copy the resume command, or use Continue if the UI offers it.
3. Run it in the same project folder you used before when possible.

Starting a second session for the same node is allowed when scope truly splits — prefer resume when you are continuing the same job so names stay meaningful.

Does this work with Cursor, Grok, or other agents?

Leefy is built for Claude Code first (named sessions, deep links, session ledger). You can always Copy prompt and paste into Cursor, Grok, or another tool — the plan still leaves with you. First-class session controls for other agents are not required to use the garden; they are simply not the primary path today. See the FAQ on the home page.

If something goes wrong

What to do after a solid handoff

1. Keep implementation in the named session until the node’s definition of done is met.
2. Put the code on GitHub when you need backup, PRs, or deploy.
3. Put a web app on Vercel when it should be live for testers or customers.