Several sessions, Needs and handoffs

One agent can run on every computer you work on. Connect a session in each project folder, on each machine, and they all show up in your agent’s direct message. Capabilities say what each session’s computer can do, the Needs field says what an item requires, and a handoff lets one session pass part of its work to another.

Several sessions#

Each folder you connect is its own session, named after the folder unless you chose another name. You can have up to 20 sessions in an organization.

• Your agent’s direct message lists them in the sessions strip, each with an online dot.
• With more than one running, the To: chip above the message box picks where new messages go, or Automatic. See With several sessions running.
• A thread stays with the session that started it. If that session ends, you can hand the thread on to another.
• Work items go to a session that reaches the item’s project. If several do, Hand to session… in the item’s thread moves it.

Capabilities#

Capabilities are tags that say what a session’s computer can do, such as windows, macos, linux, ios, android, xcode, flutter, docker, rust, web or gpu.

• When you connect, buildit-mcp suggests the tags it finds on the computer, and you confirm them on the approval screen. See Capabilities.
• Later, your agent’s details show each session’s tags. Tags Claude Code suggests but you haven’t confirmed show after “Suggested by Claude Code”, with Confirm. Edit capabilities changes them.
• Only tags you confirmed count. A session can only suggest them.
• Tags only choose among your own sessions. They never give a session more projects or permissions.

Needs#

An item’s Needs field lists the capabilities a session must have to work on it, such as macos and ios. You’ll find it with the item’s other fields. “Only a session of your agent with all of these picks this item up.” An item can need up to 10 tags.

• When you assign the item to your agent, only a session with every tag picks it up. Hand to session… lists only those sessions.
• If no such session is running, the item waits, its thread says “Claude will pick this up when a session with macos connects (work waits up to 7 days).”, and you get a notification.

Handoffs#

Sometimes a session can’t do part of its work: a session on Windows can’t build for iPhone, for example. It can then ask to hand that part to another of your sessions that can.

1. The session creates a subtask under its item, with the Needs for that part and a description of what to do. It keeps working on its own item.
2. A handoff card appears in the subtask’s thread: “Hand off DEMO-130?”, with who asks, what the subtask needs, and your sessions that match, the best one picked for you (online first).
3. The card says what the session you pick will do: it works on the subtask in that project with its own permissions and posts its progress and result in the subtask’s thread.
4. Tap Hand over, and confirm. Your tap is the go-ahead. Or tap Cancel, and it’s Not handed over.

After that:

• If the session you picked is offline, “It starts when that session connects.” The work waits up to 7 days.
• When the subtask reaches In review or Done, the session that asked hears back, with the subtask’s last comment, and carries on with its own item.
• If the session you picked can’t do it, it hands the subtask back with a reason, and you get a notification.
• If nobody picks the subtask up in 7 days, the handoff expires, and you get a notification.

A handoff card stays open 7 days. If the session you picked can’t take the subtask any more when you tap, the card says “That session can’t take it any more. Pick again.”

What a handoff can’t do#

• Sessions never message each other. Your tap is the only instruction; the session that takes over reads the subtask’s description as information.
• Only your own sessions are offered, never a colleague’s agent.
• Store uploads and release version changes still ask you on their own card, and tool approvals still apply.
• A session working on a subtask can’t hand part of it on again. It asks you instead.