Connect a coding agent to your tree

Last updated 2026-09-01

The basics

What is Agent access?

It connects your coding agent — Claude Code, Grok Build, Codex or Cursor — directly to one Leefy tree. Once connected, the agent reads the next slice in your Code wave, fetches its brief, and files its summary back into Leefy itself, instead of you carrying each of those across by clipboard.

You still plan, brief, order and approve everything in Leefy. The agent gets a door into the tree, not a say in it.

What changes about my loop?

Before: generate a brief, hand off, copy a long command, paste it into your terminal, wait, copy the agent’s summary, paste it back into Leefy. Eight steps and two clipboards, per slice.

After: brief the slices you want built, paste one line into your agent once per sitting, and watch the wave drain in Leefy. Each summary arrives on its own, with its follow-ups waiting for your click.

Do I have to use it?

No. The clipboard path is unchanged and fully supported — Copy command on a session card still carries the whole brief and needs nothing connected. See Hand off a branch to Claude Code for that path. Agent access replaces the outbound paste only, and you can go back to pasting at any time by ignoring it.

It lives under More ▸ Agent access, and it is still rolling out. If the panel says “Agent access isn’t available on this account yet”, your account is not in the rollout — nothing is broken.

A sandbox tree cannot issue tokens at all, because it has no account behind it to bind one to.

Setting it up

How do I connect an agent?

Three steps, once per tree, ever:

More ▸ Agent access → Issue token. Name it after the machine or agent that will hold it — “Laptop — Claude Code” — so you know what you are revoking later.
Pick your runner’s tab. The panel renders the exact setup command with the token already in it.
Paste that command into your terminal. Cursor is the exception: it is a config file you merge plus an in-editor approval, and the panel says so.

After that you never touch setup again unless you revoke or rotate.

The token was only shown once. How do I get it back?

You don’t. Leefy stores a hash, not the token, so it genuinely cannot show it again — the same posture as your BYOK keys. If you no longer have it, revoke that token and issue another.

That is also why the setup command renders with <your-agent-token> in it on every later visit: there is no secret left to fill in.

I pasted the command but my agent has no Leefy tools

Your agent read its config when it started. Adding a server edits a file and nothing else, so an agent that was already running has not seen it.

First time connecting a tree → restart the agent. There is nothing to reconnect to; the server does not exist in that session yet.
Rotating a token on a tree the agent already knows → /mcp → reconnect the server named after your tree is enough.

Restarting is the advice that is correct in both cases.

Can I connect more than one tree?

Yes. Each tree issues its own token, and the server is named after the tree — leefy-my-tree — so a second tree adds a second server rather than replacing the first.

That naming matters. Under a single shared name, connecting tree B while tree A was configured did nothing at all, and the agent would answer questions about tree A all day: every answer technically true, all of them about the wrong tree. So tell your agent which tree you mean — the work instruction the panel hands you already names it and asks the agent to confirm.

What is the “where your code lives” field for?

It tells Hand off to Claude Code which directory to open your editor in. Without it the editor opens in your home folder — where your repo is not, and where a project-scoped MCP config does not exist.

It is stored in your browser, on that machine only. Clearing the field clears it.

Which scope should I use?

Runner	Default scope	Worth knowing
Claude Code	This directory only	Add `--scope user` to reach the tree from every project — usually what you want
Grok Build	User (`~/.grok/config.toml`)	`--scope project` for a single repo; `grok mcp doctor` if the connection misbehaves
Codex	The file you edit	Reads the token from an environment variable, so the token goes in your shell profile and `~/.codex/config.toml` names it
Cursor	The file you edit	No `mcp add` command — merge the JSON into your existing `mcpServers` object, then approve the server or Cursor lists it without loading it

Running work

What do I actually say to the agent?

One line, once per sitting, copied from the Agent access panel. It reads roughly:

Work my Leefy wave on "<your tree>": call leefy_next_slice, check it reports that same tree, then start the slice with leefy_start_session, do the work, and file the result with leefy_submit_summary — and repeat, slice after slice, without checking back in. Stop when there are no briefed slices left, or when a slice needs a decision only a human can make.

For a single node rather than a whole wave, the session card’s ⋯ menu offers Copy agent instruction — “Do Leefy session name” — which points an already-running agent at that one brief.

It says “without checking back in” — how much will it do?

Every slice you have briefed, one after another, unattended. That is the point of it, and it is worth understanding before you paste: the agent works in your repo under your agent’s own guardrails until the briefed slices run out. Leefy is not the blast radius; your working tree is.

If you want it to stop sooner, brief fewer slices. Briefing is deliberately a human act.

How do I know it is working?

The session card and the wave rail show an Agent connected pill, driven by real traffic on your token. It lights while an agent is calling Leefy and goes out after about twenty minutes of silence — sized to a coding session, so it does not read “stopped” while the agent is deep in a long slice. Revoking a token puts it out immediately.

The rail itself is the better signal: slices move from brief-ready to in-session to done as the agent drains them.

The agent stopped and said a slice needs a brief. Why won’t it write one?

Because generating a brief spends your deliverable allowance and decides what the work is. No tool can do it. A slice at needs-brief is refused with a message naming the human action, and the agent is told to stop rather than guess.

Brief it in Leefy, then paste the work instruction again — or just tell the running agent to continue.

Does it close the wave when it’s finished?

No. Every slice landing and the wave being over are two different statements, and the second one is yours. Nothing on the agent path can stamp a wave closed.

What does the summary look like when it comes back?

Exactly like a pasted one: a session log in the stream, marked as arriving via an agent, with the same premise check and the same offers — plant these follow-ups, accept this plan.

Those offers still wait for your click. Nothing is planted, accepted, or marked done by the agent.

What the agent can and cannot do

What are the tools, exactly?

Five, and no more. Three read, two write — and both writes are things the Leefy interface already does at the press of a button.

Tool	Kind	What it does
`leefy_next_slice`	read	Reads the open Code wave and reports the next slice and its state
`leefy_get_brief`	read	Fetches a session’s brief by session name
`leefy_get_work_order`	read	Returns one task’s ordered steps as JSON — for tasks created before September 2026 only; Leefy no longer plans step-by-step tasks, so new slices arrive as briefs
`leefy_start_session`	write	Mints the session for a brief you already wrote — Handoff to Code, through a different door
`leefy_submit_summary`	write	Files a session summary and moves that session’s status

What is deliberately absent?

No tool will:

Generate a brief — that spends your allowance and is your call.
Edit the tree — no nodes, no titles, no descriptions.
Plant a follow-up or accept a plan — every offer waits for you.
See another project — a token reaches exactly one tree, and nothing lists trees.

And Leefy never runs your agent. It holds no repo, no sandbox, and none of your execution credentials. The agent runs on your machine, always, and something on your side always starts it.

Why can an agent start a session at all — isn’t that a decision?

It is the same act as taking the next ticket off a board someone else filled. The brief was written and approved by you, the wave’s order is yours, and every offer the returning summary makes still waits for your click. Without it, a hands-free wave is impossible: the agent could see the second slice and not read it.

The session it creates is identical to one you create by pressing Handoff to Code — same naming, same return contract — so the rail cannot come to disagree with the agent about a slice.

Are there slices it will refuse to start?

Four:

A slice at needs-brief — a human must brief it.
A node on a frozen season.
A task- or step-scoped brief — those need tree writes this tool does not have, so it names the door in Leefy instead.
A slice already in a session — it hands back the existing session name rather than starting a second one.

Cost

Does connecting an agent cost me anything in Leefy?

No. No tool makes an AI call, so nothing is spent from your deliverable allowance — Leefy serves bytes it already has.

Your agent still burns its own tokens against your Claude, Grok or OpenAI arrangement. That is unchanged, and it is where the real cost of a wave sits.

Is there a rate limit?

About sixty requests a minute per token. It exists to catch a misbehaving agent loop, not to meter you — a normal wave is nowhere near it. If you do hit it, the server says how long to wait.

Security

How safe is the token?

It is a bearer token that lives in plain text in a config file on your machine — inherent to how every MCP client authenticates today. What limits the damage:

It is scoped to one tree, and no tool can reach another.
It is hashed at rest, so a Leefy-side leak yields nothing usable.
It cannot spend your allowance or change your tree — see the tool list above.
Revocation is immediate. No cache sits in front of it.
The leefy_at_ prefix makes a leaked string easy to search for and attribute.

What if a laptop is lost, or a token leaks?

Revoke it under More ▸ Agent access and issue a new one. Revocation takes effect on the very next call; the agent holding it simply stops being able to reach the tree.

Can a connected agent read my whole tree?

It can read what a brief already carries — the wave, the slice briefs you generated, and (for tasks that predate September 2026) task work orders for that one tree. It cannot browse the tree, and it cannot see any other tree or project.

Is an agent-submitted summary trusted?

It is treated exactly like a pasted one: agent-authored text stored as a log body, at the same trust level.

Worth knowing, though — removing the paste step also removes the moment where you might have noticed something odd in a summary. Skim the ones that matter.

If something goes wrong

Symptom	What to try
Agent connected but reports no tools	It read its config at startup — restart it. If that fails, update your runner: an old client may speak a protocol revision that has moved on
“No wave is open on this tree”, but you are looking at one	Almost always the wrong tree. Every tool answer names the tree it came from — check it matches your screen, then restart the agent in the right project
Submitting the summary was rejected	The parse error goes back to the agent, which wrote the block and can fix it. Failing that, copy the block and paste it into Leefy the old way
Hand off to Claude Code does nothing	It hands a `claude-cli://` link to your operating system, which not every setup answers. Use Copy command beside it — that carries the whole brief and needs nothing connected
Not sure which button to press	Hand off to Claude Code opens your editor and tells it to fetch the brief itself, for a connected agent. Copy command carries the entire brief and needs nothing

What to do next

Line up a wave and brief the slices you actually want built — that is the spend decision, and it stays yours.
Paste the work instruction once, then watch the rail rather than the terminal.
Accept each summary’s offers as they land, and close the wave yourself when it is genuinely over.