Skip to navigation

Agents and Teams in Band Desktop

Add coding agents from the Library or from scratch, set what each one may do without asking, and manage them.

Band Desktop, formerly Jam, runs coding agents on your machine for you. Add ready-made agents and teams from the Library, or set one up yourself, then choose how much each agent may do without asking.

Prerequisites

  • Band Desktop installed and signed in. See Install and Set Up Band Desktop.
  • At least one coding agent installed and signed in on this machine, such as Codex or Claude Code.
  • To use Codex, GitHub Copilot, OpenCode, or Antigravity, the runtime turned on in Settings > Integrations. See Band Desktop Settings.

Add Agents from the Library

To add a ready-made agent, open Agents and select Browse Library. Under Predefined agents, choose a Runtime on the agent’s card and select Add.

Band Desktop Library with six predefined teams, each with an Add team button, and predefined agents below, each with a runtime picker and an Add button or an Added mark

The 16 predefined agents are Implementer, Reviewer, Planner, Investigator, Test author, Security reviewer, Performance engineer, Integrator, Release engineer, Technical writer, Triage, Developer, Writer, Product manager, Architect, and Ops. The Runtime picker lists the runtimes this machine can run, in the order Codex, Claude Code, GitHub Copilot, ACP agent, then OpenCode. Codex, GitHub Copilot, and OpenCode appear only after you turn them on in Settings > Integrations. Band starts an agent added here when work arrives for it, so you never open a terminal for it.

An agent you already have is marked Added; select its card to edit it. If one of your own agents already uses the name or handle, Band numbers the Library copy, such as Planner 2 and planner-2.

Add a Ready-Made Team

Under Predefined teams, each member row has its own Runtime picker and Add, so members of one team can use different runtimes. Add team creates the members you do not have yet, and an agent can belong to more than one team.

TeamWhat it doesMembers
Feature crewPlans, builds, tests, reviews, and lands a feature end to end.Planner, Implementer, Test author, Reviewer, Integrator
Bug squadFinds the cause, fixes it, and pins it with a test.Investigator, Implementer, Test author
Release crewHardens, documents, and ships what was reviewed.Security reviewer, Technical writer, Release engineer
DeliveryPlans, reviews, builds, and reviews a piece of work, ending at a local branch.Delivery Manager, Plan Author, Plan Reviewer, Code Author, Code Reviewer
ExpressBuilds and reviews a small change without a plan, ending at a local branch.Express Lead, Express Author, Express Reviewer
ArchitectsWrites and reviews an implementation plan, and stops there.Architect Lead, Architect Author, Architect Reviewer

While members are created, the button shows Adding N of M…, then View team. If a member fails, the button changes to Try again and the failed member shows Edit.

Create an Agent

To set an agent’s name, instructions, project folder, or model yourself, open Agents and select New agent. Nothing is created until you select Create agent on the last step.

1

Identity

Fill in the agent’s identity:

FieldWhat to enter
NameThe display name, such as Security Reviewer.
HandleThe agent’s handle in Band.
DescriptionAt least 10 characters. Shorter text shows “Description must be at least 10 characters.”
TagsOptional. Press Enter to add each tag.
InstructionsOptional. See Agent Instructions.

Select Continue.

2

Runtime

Choose the runtime: Codex, GitHub Copilot, Claude Code, OpenCode, or ACP agent. The form starts on Codex. Codex, GitHub Copilot, and OpenCode appear only after you turn them on in Settings > Integrations. Antigravity appears as its own choice when Band detects it and you turn it on in Settings.

In Working directory, enter an absolute path to the project folder, or leave it blank to use a workspace Band manages. A relative path shows “Working directory must be an absolute path.”

Set the runtime’s options. They are listed per runtime below.

Runtime check starts the runtime once and stops it to confirm the settings work. It checks Runtime configuration, Local agent identity, and Workspace, plus Docker Sandbox for a sandboxed agent, and reports Ready., Ready, with a warning., or the failing part. To run the check again, select Test runtime (Connect for an ACP agent); after a failure the button reads Try again. If Band found the wrong program, select Choose the executable.

3

Review

What Band will create summarizes the agent. The Authentication row shows the login the runtime already has: Band supplies no credential to any runtime. Select Create agent.

New agent Runtime step with Claude Code selected among Codex, GitHub Copilot, OpenCode, and ACP agent, Permission mode set to Auto, Launch details collapsed, and a passed Runtime check beside Test runtime

After Create agent, Band returns you to where you started, the Library, a team’s page, or the Agents list, and shows the toast “Security Reviewer added. It is on your Agents page.”

The Model picker offers Always follow the runtime’s default, for example Always follow Codex’s default. A new agent left on the default is saved with the runtime’s current default model, so a later change to that default does not change the agent. To track the default instead, choose Always follow explicitly. Runtime options take effect the next time the runtime starts.

OptionWhat it sets
ModelThe Codex model.
Reasoning effortCodex reasoning effort.
Approval policyWhen Codex asks for approval. See Permission Modes by Runtime.
Codex tool accessHow much of the disk and tools Codex can use.
Web searchWhether Codex can search the web.
Compaction budget (input tokens)The input-token count at which Codex compacts its context. Set it below the model’s context limit; empty uses the environment default and 0 disables proactive compaction.
OptionWhat it sets
Claude customizationsUse my Claude setup inherits ~/.claude, including hooks, skills, CLAUDE.md, MCP servers, and your existing Claude Code login. Minimal credentials-only mode runs Claude Code with --bare, skips your customizations and keychain login, and needs credentials in the environment of jamd, the Band daemon. The agent’s Runtime tab calls this field Context.
ModelThe Claude model.
Reasoning effortClaude Code reasoning effort.
Permission modeWhat Claude Code may do without asking. See Permission Modes by Runtime.
Denied toolsTools the agent may not use.
MCP serversinherit yours or only Band’s.
OptionWhat it sets
ModelThe model.
Reasoning effortReasoning effort.
Approval policyWhether permission requests are asked, allowed, or denied.

The ACP agent field lists the ACP registry copy shipped with Band Desktop 0.4.18, with Custom command first. Each entry shows Tested by Band with a version, or not tested by Band, and Installed, Not installed, or Couldn’t check. Tested agents sort first.

ACP agent list on the Runtime step, with Custom command at the top and registry agents marked tested by Band or not, installed or not installed

If the chosen agent is not installed, do one of the following:

  • Run the install command Band shows, then select Recheck.
  • Select Install, when Band can install the agent itself. Antigravity may then ask you to Sign in with Google.
  • Select Locate… to pick an executable Band did not find.
  • Select Use built-in to switch to a runtime Band runs directly.

The options below the picker stay disabled until the chosen agent is installed. An agent that needs environment settings is listed with “Needs environment settings Band can’t apply yet” and cannot be chosen.

OptionWhat it sets
ModelThe model. Shows Agent default when unset.
Agent modeThe agent’s mode. Shows Agent default when unset.
Approval policyWhether permission requests are asked, allowed, or denied.

Permission Modes by Runtime

Each runtime has its own setting for what an agent may do without asking you. A new agent starts with the value in the Starting value column. These settings apply to agents Band Desktop runs; for coding agents connected through the SDK adapters, see Approval Mode.

RuntimeSettingStarting valueChoices
CodexApproval policyOn requestNever ask rejects approval requests. On request prompts for approval. Untrusted only prompts for unverified actions.
CodexCodex tool accessFull accessRead-only views files and makes no changes. Workspace write edits workspace files. Full access has unrestricted tool and disk access.
Claude CodePermission modeAutoPlan proposes and never acts. Default is read-only without a broker. Don’t ask uses pre-approved tools only. Accept edits allows file edits and common shell commands. Auto allows everything, behind a safety classifier. Dangerously skip permissions runs no checks.
GitHub Copilot, OpenCode, ACP agentApproval policyAllow automaticallyAlways ask prompts for approval. Allow automatically approves all requests. Deny all rejects permission requests.

For Codex, approval and tool access are independent. Never ask runs operations that Codex tool access already allows and rejects sandbox escapes without prompting. It does not mean deny all or Full access.

The Claude Code Permission mode picker lists only the modes the runtime check reports as usable. Use the default (default) names the mode the runtime starts with when you pin none.

To clear every standing answer an agent holds, open the agent, select the Runtime tab, and under Standing answers select Remove all. Answering requests is covered in Rooms in Band Desktop and, from Home, in Assign and Follow Work.

Owned Runtimes

Every agent you add from Browse Library or New agent is an owned runtime: Band starts the coding agent process on this machine and restarts it with Restart agent. A session you start yourself and connect to Band is an attached runtime, covered in Connect Your Own Sessions to Band Desktop.

An owned Codex, GitHub Copilot, OpenCode, or ACP agent stops after 600 seconds without activity and starts again on the next message. It stays in its rooms while stopped. An owned Claude Code agent keeps running between messages. To change the idle time, set Stop idle agents after (seconds) in Settings.

Run an Agent in Docker Sandbox

To run one agent inside a Docker sandbox, open Launch details on the Runtime step and set Docker Sandbox:

ChoiceEffect
Use global defaultFollows Run new agents in Docker Sandbox by default in Settings.
Sandbox this agentRuns this agent in Docker Sandbox.
Run this agent on the hostRuns this agent directly on this machine.

Docker Sandbox requires Docker Sandboxes v0.47.0 or newer, with the provider’s credentials set up in Docker. A sandboxed Codex agent gets full access inside the sandbox, and Docker controls what it can reach on this machine. To run an SDK agent of your own in a Docker Sandbox instead, use the Docker Sandbox (sbx) Kit.

Agent Details

To open an agent, open Agents and select the agent’s card.

Developer agent page with its tab strip and the Agent actions menu open, listing New room with agent, Edit agent, Duplicate agent, Agent in Band, Restart agent, Stop agent, Archive agent, and Delete agent
TabWhat it shows
OverviewUsage for Today, 7D, or 30D, Messages, Cost per day, Model mix (cost), Rooms, and Warnings and errors.
WorkThe agent’s work, grouped by Status or Room with Group by. Done work untouched for 12 hours leaves the board. Show archived (N) brings it back.
InstructionsThe agent’s instructions. See Agent Instructions.
RuntimeRuntime setup with Edit, Test, and Disable, Current errors, Settings with Save settings, permission controls with Standing answers, Capacity, and Advanced Docker operations for the Agent, Runtime host, or Selected room.
SessionsOne row per room session, with Reset runtime and Unbind room in each row’s menu.
ContactsThe agent’s contacts. Shown only when the agent has a Band ID. See Work with Coworkers in Band Desktop.
ActivityThe agent’s recent activity events, with the raw log when available.
InfoProfile, Host, Working dir, Agent id, Usage attribution, and Agent API key with Save key when available.

The Room activity feed setting on the Runtime tab controls whether the agent’s tool use and reasoning appear in its rooms: Use default, Nothing, Tool calls, or Tool calls and reasoning.

Restart or Stop an Agent

Open the agent and select Agent actions . The menu holds New room with agent, Edit agent, Duplicate agent, Agent in Band, Restart agent, Stop agent, Archive agent, and Delete agent, each shown when it applies. When another Band client owns the agent, Reclaim agent replaces Restart agent. Lifecycle actions are disabled while one is running.

  • Restart agent restarts the agent worker and all of its owned runtime sessions. Attached sessions must be restarted in their own host.
  • Stop agent asks Stop followed by the handle. Confirming with Stop agent ends the agent worker and all of its runtime sessions, and keeps the agent, its rooms, and its work. Restart the agent to bring it back online. Stop agent is disabled when the agent is already stopped.

To act on one room only, open the Sessions tab and open the row’s menu:

  • Reset runtime recreates the owned runtime for that room and keeps the room binding.
  • Unbind room stops that runtime session and removes its room binding, after you confirm.

To stop or resume an agent from inside a room, see Rooms in Band Desktop.

Change an Agent’s Settings

Do one of the following:

  • Select Agent actions > Edit agent. The same three steps open with the agent’s settings filled in and end in What Band will save.
  • Open the Runtime tab, change Settings, and select Save settings.

Runtime settings take effect the next time the runtime starts.

For an ACP agent, Runtime setup shows the agent, its reported version (Version unknown if it reports none), and a newer registry version when one exists. To switch to a different ACP agent, select Change agent…, then choose how Existing room sessions take the change: New sessions only, or Apply and restart N for the affected room sessions. Change agent… is unavailable for an agent in Docker Sandbox. Turn off Docker Sandbox for that agent, or create a new agent.

Agent Instructions

Instructions tell the agent its role. On the Identity step, set them in one of three ways:

OptionWhat it does
Use a presetStarts from a built-in role: the 16 Library roles, plus Migration engineer.
Choose instructions fileLinks a .md, .markdown, or .txt file. Text you type under Additional instructions is read after the file.
The instructions boxType the instructions yourself.

To change instructions later, open the agent’s Instructions tab and select Choose another file, Remove file, or Clear, or edit the text. If the linked file is missing or unreadable, the tab shows Band can’t currently read this file. A runtime without saved-instruction support shows “This runtime does not support saved instructions.”

Duplicate, Archive, or Delete an Agent

All three actions are in Agent actions on the agent’s page.

  • Duplicate agent asks for a name. Continue opens New agent with the source agent’s runtime setup and instructions filled in. Nothing is created until Create agent.
  • Archive agent asks Archive followed by the agent name. Confirming removes the agent from Band Desktop and keeps its Band identity so you can restore it.
  • Delete agent asks Delete followed by the agent name. Delete permanently removes the agent identity from your account and stops its runtimes. Rooms and messages stay, and the identity cannot be restored.

To restore an archived agent, open Agents, select Archived agents (N) at the bottom of the list, and select Unarchive on the agent’s card. The button shows only when at least one agent is archived.

Delete Several Agents at Once

  1. Open Agents and point at an agent in This machine.
  2. Select its checkbox. The header shows N selected, a checkbox to select every agent on this machine, Cancel, and Delete (N).
  3. Select more agents, then select Delete (N) and confirm Delete N agents?.

One delete takes at most 100 agents, and the header says so when you reach the limit. Agents that could not be deleted stay listed with the reason and a Retry N button.

Find Agents

The Agents list has two groups, This machine and External. To narrow it, type in Search agents… or use the filters:

FilterValues
WhereThis machine, External
ProviderEach provider name, and External
RuntimeHeadless (owned runtimes), Terminal attached (attached runtimes), Nothing attached, External
TagsEvery tag on your agents, alphabetically. Shown only when at least one agent has a tag.

Each agent card has its own Agent actions menu with Copy handle, Open agent, New room, and, for agents on this machine, Delete agent.

Create Your Own Team

To group agents yourself, open Teams and select New team. In Create a team, enter a Name and Description, pick the members under Agents on this team, optionally add Team guidelines, and select Create team.

A team’s page shows Members, Team guidelines, Edit team, and New room, which opens a room with the team’s members on your roster. Delete team is in the team’s Actions for menu . The Assign work picker on Home lists agents only, so to give a team work, select New room on its page and brief the members there.

Next Steps