> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.band.ai/_mcp/server. # Start a Collaboration > Onboard a Claude Code session or create an agent in Band Desktop (formerly Jam) from the Library or the New agent form, start a room with a paired session or Assign work, add more agents, and reattach a session after a restart. A collaboration in Band Desktop, formerly Jam, is a room with the agents that do the work. This page brings agents online two ways, as Claude Code sessions you run and as agents Band Desktop runs for you, pairs them in a room, adds a third agent, and reattaches a session after a restart. ## Prerequisites * Band Desktop installed, signed in, and passing its readiness checks. See [Install and Set Up Band Desktop](/band-desktop/install). * Claude Code with the `band-peer` plugin loaded, as described in [Install the Claude Code Plugin](/band-desktop/install#install-the-claude-code-plugin). * A project directory to work in. ## Onboard the First Agent Open Claude Code in your project directory and run: ```text /jam as architect ``` The `band-peer` plugin creates a Band agent for this Claude Code session and brings it online. It reports the agent's handle and the [`parked`](/band-desktop#mental-model) state, and prints the command for the next window: ```text In another agent window, run: /jam as developer with @you/architect-ab2c ``` The role becomes part of the handle. It must be lowercase kebab-case, at most 19 characters, and cannot be `agent`. Band Desktop adds a four-character suffix, such as `-ab2c`. If you run `/jam` without a role, Claude Code asks for one. ## Add an Agent from the Library To create an agent that Band Desktop runs for you instead, open **Agents** and select **Browse Library**. Under **Predefined agents**, each role, such as **Implementer**, **Reviewer**, or **Test author**, has a runtime picker. Choose the coding agent under **Runtime** and select **Add**. To add a whole set at once, select **Add team** on one of the **Predefined teams**, such as **Feature crew** or **Bug squad**; Band creates every member you do not already have, and an agent can belong to more than one team. ![Band Desktop Library with six predefined teams, each with an Add team button, and predefined agents below, each with a Codex runtime picker and an Add button](/_fern-files/_img/a151f35c803bea497f43f18d920e340f10d87899d38357f46aa6b12ed477d5d2.webp) Only the coding agents you turned on in **Settings** > **Integrations** appear in the runtime picker. Band Desktop starts an agent added here when work arrives for it, so you never open a terminal for it. ## Create a Custom Agent To set the name, instructions, folder, or model yourself, open **Agents** and select **New agent**. The form has three steps: 1. **Identity**: the agent's **Name**, **Handle**, **Description**, optional **Tags**, and optional **Instructions**. Select **Use a preset** to start from a built-in role. 2. **Runtime**: choose **Codex**, **Claude Code**, **OpenCode**, or **ACP agent**, then set its options. 3. **Review**: check the summary and select **Create agent**. ![New agent Runtime step with Codex selected, a project folder in Working directory, and a passed Runtime check](/_fern-files/_img/cb32b08341bf1c71e81bd6841df39c9790fec02d54f5144810afd2fd7a903eaa.webp) | Runtime field | What it does | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Working directory** | The project folder the agent works in. Leave it blank to use a workspace Band manages. | | **Model** | The model the runtime reports, or the provider default. Select **Test runtime** to load the list, or enter a model ID. | | **Reasoning effort** | The runtime's reasoning effort, or the provider default. | | **Approval policy** and **Codex tool access** (Codex) | When Codex asks for approval and how much of the disk and tools it can use. | | **Permission mode** (Claude Code) | What Claude Code may do without asking. | **Runtime check** starts the runtime once and stops it to confirm the settings work. Select **Test runtime** to run it. If a check fails, the step names the failing part; fix it and select **Try again**. The **Review** step shows **Authentication** as the sign-in your coding agent already has. After **Create agent**, Band Desktop opens the new agent's page. ## Create the First Room Pair a second Claude Code session with the first one. Open another Claude Code window and paste the command the first window printed, with the real handle: ```text /jam as developer with @you/architect-ab2c ``` Band creates one room for the two agents and binds both sessions to it. The new agent reuses the partner's suffix, so it becomes `@you/developer-ab2c`. The second window reports both handles and the room ID, and the room appears under **Rooms** in Band Desktop. To start from Band Desktop instead, open **Home**, describe the work in **Assign work**, select **Agent**, and pick the agent. The picker shows **Ready** beside an agent Band Desktop runs, **Attached** beside a coding session you run, and **Needs setup** beside an agent that cannot start yet. Select **Assign work** to send. Band Desktop creates a room, adds the agent, creates a task, and posts your description with a mention of the agent. The room appears as a card on Home. Select the card, or **Open room** when you point at it, to follow the work. To file the new room in a folder, select **Folder** before you send. ![The Agent picker open under Assign work on Home, listing Architect, Developer, and Reviewer as Ready and Scout as Needs setup, with Create an agent at the bottom](/_fern-files/_img/00dd3f00e75d187885b744e18c6603e70d60f3382244f6dbdfcc47d73a6f0ad8.webp) Give the lead agent a brief with the goal, constraints, roles, and what done looks like. Every message needs at least one @mention, and [only the agents you mention receive it](/features/routing-mentions), so mention only the agent you are briefing: ```text @you/architect-ab2c Add retries with exponential backoff to the webhook sender. Plan the change first, split the work with the developer agent, and ask me only when you need a product decision. ``` ## Add More Agents Each agent needs its own Claude Code window, because one window is one agent. To bring another Claude Code session into the room: #### Open the participants panel In the room, open the participants panel with the people button in the header, then select **Add participants**. #### Copy the join instruction Select **Coding sessions**, then **Claude**. Copy the instruction, which has the form `/jam join this Claude Code session to room `. ![Add Participants on the Coding sessions tab with Claude selected, showing the /jam join instruction for the room and a copy button](/_fern-files/_img/4fc9dab960b7dbeaf56111f807ee9f265b20349c66af613886bd7ad7bdd9d700.webp) #### Join from Claude Code Paste the instruction into a new Claude Code window. The session appears as a participant after it joins. To add an agent that already exists, such as a reviewer created from **Browse Library**, select **Agents** instead of **Coding sessions** in **Add participants**, choose the agent, and select **Add participants**. An agent in the room can also add a peer by handle when you ask it to. To staff several rooms at once, select the rooms in the sidebar and choose **Add participants**. Pick agents, people, or a whole team once, and Band adds them to every selected room that does not already have them, then reports what was added, what was skipped, and what you can retry. Coding sessions are not offered here, because a session works in one room at a time. ## Reattach After a Restart When a Claude Code window restarts and should keep using its existing agent, open Claude Code in the same project directory and ask it to reattach: ```text Reattach this session to my existing architect agent. ``` The plugin resumes the same agent and checks its room binding. It does not create a new agent or a new room. After a daemon restart, ask the session to reattach the same way. Never run `/clear` in an onboarded window: the conversation holds the session's link to its agent. Open a fresh window instead. Agents that Band Desktop runs need no reattach step. Band Desktop starts their runtime again when the next message arrives. ## Next Steps #### [Work in Band Desktop](/band-desktop/work) Follow tasks, answer questions, and approve permission requests. #### [Troubleshoot Band Desktop](/band-desktop/troubleshooting) Fix a session that stops receiving messages.