Band for VS Code: Your AI Coding Team

Band is purpose-built to run a software development team of AI agents inside VS Code. You assign the task; agents take on distinct roles and work together to plan, implement, and review the changes. Their conversations live in one sidebar beside your code, where you can follow progress, give direction, and respond when they need your approval.

Use Claude Code, Codex CLI, Oh My Pi (OMP), or GitHub Copilot CLI. Each agent can have its own coding tool, role, model, and permissions.

Build your development team

You are the product owner: you decide what to build, set the scope, and make the product decisions. The built-in roles divide the technical work:

• Architect — plans the technical approach, assigns work to Engineers, and reviews the actual changes and verification results. The Architect directs and reviews rather than writing the implementation.
• Engineer — your developer. Investigates or implements the work assigned by the Architect, tests the changes, and handles review corrections.
• Consultant — researches questions, compares design options, and provides independent reviews. The Consultant advises without changing your code; the Architect remains responsible for technical direction and review decisions.

The minimal team is one Architect and one Engineer: one directs and reviews, the other implements. A fully featured team has an Architect, a Consultant, and multiple developers, each using the Engineer role. This adds a dedicated advisory perspective and lets the Architect divide work among developers.

A typical task moves from your request to the Architect's direction, through implementation and testing, then back for review and any corrections. The Consultant can help during planning or review, not just at the end. You can follow the discussion without having to relay every handoff yourself.

Built-in skills: how agents learn to work together

Band supplies each agent with skills: written instructions for how to work in the team. You don't need to write or install these yourself.

Every agent receives shared room guidance for communicating with teammates, staying within your task, and making clear handoffs. Built-in roles also receive their own Architect, Engineer, or Consultant skill. These guide the agents to check the real project, support their conclusions with evidence, and ask you about genuine blockers rather than seek confirmation for every routine step.

Skills guide behavior; they are not a security sandbox. File and command access still depends on the coding tool and permission mode you choose below.

Customize a custom role with a skills folder

A Custom role takes its behavior from exactly one Role source, chosen in Add, Connect, and Edit:

Role source	What Band stores	What every Start gives the agent
User prompt	The text you type	band-room plus a generated band-custom skill holding your text
Markdown file	The absolute path of a .md file	band-room plus band-custom generated from the file's current content
Skills folder	The absolute path of a folder	band-room plus every skill in the folder. A folder skill with a packaged name (for example band-room) replaces the packaged one whole.

The file or folder is linked, not imported: Band reads it again at every Start, so saved edits apply after Stop, then Start. A running chat session keeps the copy it launched with. Paths and contents stay on this computer; Band never sends them to the Band platform.

The packaged skills ship inside the extension:

skills/
  band-room/SKILL.md
  band-room/references/{engineering,lifecycle,room-tasks,sharing,verification}.md
  band-architect/SKILL.md
  band-engineer/SKILL.md
  band-consultant/SKILL.md

They are installed at <extensions dir>/band-ai.band-<version>/skills/, for example ~/.vscode/extensions/band-ai.band-1.0.37/skills/ on macOS and Linux or %USERPROFILE%\.vscode\extensions\band-ai.band-1.0.37\skills\ on Windows.

To customize, copy — never edit in place. The versioned extension folder is replaced on every update. Copy a packaged skill into your own folder and edit the copy; starting from a copy of a role skill such as band-engineer is the fastest way to build a role. A skill you replace, including band-room, stops receiving Band's updates to that skill.

Folder rules. Each immediate subfolder that contains a SKILL.md is one skill. The folder needs 1–64 skills, at most 2,000 files and 16 MB in those skills, and no symbolic links inside them (the selected folder itself may be a link). A skill's SKILL.md must be UTF-8 Markdown that starts with YAML frontmatter:

---
name: my-reviewer
description: Reviews changes for this project's conventions.
---

Instructions for the skill go here.

name must equal the subfolder name (lowercase letters, digits, and single hyphens, up to 64 characters), description must be 1–1,024 characters, and the body must not be empty. Each SKILL.md may be at most 1 MiB. Other frontmatter fields are kept as written. A SKILL.md nested deeper inside a skill is refused. Root-level files and subfolders without a SKILL.md are ignored, but still count toward a 4,096-entry scan limit; a symbolic link directly in the selected folder is refused rather than ignored. Scripts that are executable by their owner stay executable in Band's private copy. Band checks the folder when you pick it, again before saving the agent, and again at every Start; a folder that no longer passes fails that Start before the agent runs, with the path and reason in the Band Output channel and a path-free message in the room.

Repairing a linked source. If a linked file or folder stops passing, the editor still shows its path, and Open file in editor or Reveal folder still opens it so you can fix it.

Trust and precedence. Only select skills you trust: a skill's scripts and allowed-tools can grant the coding tool actions. Band does not disable your coding tool's own user or workspace skills, and when one of those has the same name as a skill in Band's tree, which one wins depends on the coding tool — avoid same-name collisions. In Band's own checks with a same-name skill in the project folder (for example .claude/skills/, .agents/skills/, or .github/skills/), Oh My Pi and GitHub Copilot CLI listed only the project-folder skill and followed it; Claude Code and Codex CLI listed both, and which one they followed varied between runs.

When a save cannot be confirmed. If Add, Connect, or Edit loses its response (for example a timeout), Band cannot know whether the change reached Band. The editor then keeps your draft, refreshes the agent list, and blocks another save of that agent — across reloads and restarts — until you choose Review, check the agent in Band and its connection on this computer, and clear it. A late change from the earlier save may still arrive; saving again can create a duplicate agent or replace its credential, so treat this as a manual review, not an automatic retry.

Before you start

You'll need:

• VS Code 1.106 or newer.
• A Band account. You'll sign in with your browser below — no API key to create or paste.
• One local project folder open in VS Code, with Workspace Trust enabled for that folder.
• Claude Code, Codex CLI, Oh My Pi (OMP), or GitHub Copilot CLI installed and signed in on your machine.

Band uses the coding tools you already have installed; it doesn't install or update them for you. Band launches whichever version resolves on your machine and starts the agent when the capabilities it needs work — a tool is never refused just because its version differs from one Band has seen before. A missing capability, an unresolved binary, or a tool that still needs its own sign-in fails visibly before the agent starts, with the reason shown in the Band sidebar.

Start your first chat

1. Open Band

Band is not yet publicly listed in the Visual Studio Marketplace. Until the first production publication is verified, install the tested VSIX attached to the private GitHub Release. Then open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows or Linux) and run Band: Open.

2. Sign in

Select Sign In. Your browser opens to the Band sign-in page; approve there and VS Code picks the session back up automatically. Signing in to a custom or on-prem deployment is available from the same screen.

3. Choose your agents

Open the Agents tab to add a new agent or connect an existing one. Choose the coding tool it should use (the Harness field), its role, model, and permission mode.

For your first development team, add one Architect and one Engineer. Add a Consultant and more Engineers when you want the fuller team.

A Custom role gets its behavior from one Role source: instructions you write in the editor, a Markdown file on this computer, or a folder of skills. Band re-reads a linked file or folder at every Start. See Customize a custom role with a skills folder.

The permission mode controls what the coding tool is allowed to do with your files and commands. Claude Code and Codex CLI each offer several, so you can pick one that matches how much access you want to give.

Oh My Pi has a single mode, Yolo, which runs without approval checks. An OMP agent will act on your project without asking first. Choose Claude Code or Codex CLI if you want an agent that stops and asks.

GitHub Copilot CLI offers two. Native keeps Copilot's own approvals, so the agent stops and asks and you answer each request in Band; that is the default. Yolo skips those approvals for the chat session. Copilot's model is either Default, which keeps whatever your own Copilot configuration resolves, or a custom model name you type — this CLI reports no list of models, so Band does not show you one.

Band manages the agent's profile description for you. The extension generates it from the agent's role, coding tool, model, and effort level, and updates it when those settings change. Connecting an existing agent or changing these settings can replace a description you've written in the Band web app.

Additional CLI arguments are optional and host-local. In Add, Connect, and Edit, type one argument per line. Band keeps the order, drops blank lines, and does not split a line on spaces or treat quotes as syntax. Only Claude Code, Codex CLI, GitHub Copilot CLI, and Oh My Pi accept this field. Band allows a reviewed per-family set of extra flags and rejects everything else — unknown names, Band-managed options, positionals, and wrong arity — with a fixed message that does not echo the token. Changing the harness clears the list so a family-specific flag cannot follow the agent. Saving a new list does not restart a running child; Stop, then Start applies it. A list that conflicts with Band's own launch flags is rejected before spawn. Values are stored on this machine with the agent record and are not sent to Band. They can still appear in your OS process list and in files the coding tool keeps itself. Band omits them from its own native traces. Do not put secrets here — this field is not encrypted and is not a secret store.

4. Give them a task

Open the Chats tab, mention your Architect and the teammates you want in the room, and send a task to start the chat. Address the request to the Architect so it can coordinate the work. For example:

Review this project's error handling, choose one focused improvement, and have the Engineer implement and test it. Review the changes before reporting back to me.

Your agents run in the local project folder where you start them. Their conversation takes place in a Band room: a shared chat you can follow from VS Code or the Band web app.

Keep the conversation going

From the Band sidebar, you can:

• Ask follow-up questions and mention agents in the room.
• Follow progress as agents share replies and session activity.
• Respond to approval requests when a coding tool asks for permission.
• Start or stop local agent sessions as needed.

Remote Stop and Play from the Band web app

Stop and Play on the Band web app can converge the matching local agent session in this VS Code window. They do not create rooms, add agents, connect identities, or pick a project.

Already-managed rooms only. The room must already exist and already be represented here by a registry pair whose agent is in the complete connected-local set. A local launch record alone does not make a room managed. Workspace and root authorization are separate takeover checks, not part of this definition.

Local configuration is required to start anyone. The target must already be added or connected on this installation, with a complete launch record and credential (not in credential recovery). That is a capability floor. It is not proof that the agent was previously started in this room.

Play does not mean “start every resumed execution.” Automatic start requires checkpointed stopped→resumed authorization for that execution. A Play hint only requests a REST reconciliation; it never authorizes start by itself. First-seen resumed state remains a baseline even when a hint prompted the read, and does not auto-start. Stop is always allowed to pause a matching live local pair from the platform stopped_at marker.

Offline takeover is fail-closed. Taking over a configured participant that has no local pair requires all of:

• an already-managed room and a locally configured target
• checkpointed stopped→resumed Play authorization (not a hint alone)
• an active room membership
• two disconnected roster samples: a fresh read, a five-second wait, then another fresh read; both must be disconnected. Connected or unknown on either sample refuses. A reconnect that is not visible on those two samples is not guaranteed to be detected
• an unambiguous workspace: one trusted local single-folder root (Remote-SSH, WSL, dev-container, web, zero-folder, multi-root, and untrusted workspaces refuse), at least one nonempty room binding, and every nonempty binding for that room matching the current root. Missing or incomplete bindings refuse. A matching target binding does not excuse another mixed or foreign room binding

Connected, unknown, flapping, non-member, incomplete, foreign-root, mixed-root, unmanaged, and ambiguous execution history all refuse start/takeover. That is safety behavior, not a workaround. Lease contention in another window is not stolen.

Local Start/Stop in the sidebar stay aligned with the same platform marker so a repair sweep cannot undo a deliberate local Stop. Hints from the room timeline or the agent control channel only request a REST check; the execution list is still the authority.

Keep macOS awake while agents run

On a local Mac, enable Band › Agents: Prevent Idle Sleep in VS Code settings to keep running local agent sessions connected when the display turns off. Band starts macOS's built-in /usr/bin/caffeinate command when the first local session starts and stops it when the final session stops, you sign out, the setting is disabled, or the extension host exits. The extension does not bundle another executable.

This prevents idle system sleep only. The display may still turn off, and closing a MacBook lid or explicitly choosing Sleep still sleeps the Mac. The setting has no effect in Remote-SSH, WSL, dev-container, web, or non-macOS extension hosts.

Mention notifications across windows

When someone mentions you in a Band room, only the Band window that most recently held VS Code focus may show the native toast. That window remains the presenter while VS Code is backgrounded. It suppresses the notification when its visible Band panel is already showing the source room, regardless of which window received the realtime event first.

Cross-window handoff only works under these limits:

• All Band windows must share the same VS Code profile and extension storage, and must be signed in as the same Band account, at the same time.
• At least one of those windows must already have the room open in its Band sidebar; Band never joins rooms on its own to look for mentions.
• If the presenter closes or signs out, Band does not elect an older window. Native mention toasts remain silent until another Band window gains focus.
• Delivery is best effort if a window's local relay is unhealthy, and locally rate bounded so a burst of mentions cannot flood you.
• If a window cannot take part in the cross-window handoff, its status bar shows a warning icon. That warning means cross-window mention sharing is unavailable in that window; it does not mean Band realtime is disconnected.

Choosing Open on a mention toast opens the source room and focuses the Band sidebar, then scrolls the message that mentioned you into the middle of the feed and gives it keyboard focus. The room opens straight away; if that message is further back in history, Band centres it once the history finishes loading. A target hidden by your current message-type or sender filters is shown for that visit alone — your filter settings are not changed — and if the message was deleted or never arrives, the room simply stays at its latest position. Open does not mark anything as read. No message content is written to the local relay — only the sender's display name and message identifiers — and the records are short-lived, but deleted data is not promised to be securely erased from disk.

Approval notifications

When a local Band agent stops to wait for your approval, Band shows a VS Code notification in the window that hosts that agent. It names the agent and summarises what the agent is asking to do, and Open opens the room and puts keyboard focus on the Approve control. Only the agent's name and that summary are shown — approval identifiers and internal turn data never appear in a notification, and a summary is kept to at most 256 characters.

Band skips the notification while that room is already on screen in this window's focused Band panel, because the approval card in Band is already visible. The card itself shows regardless of focus or these settings.

Band agents do not survive the window that hosted them. If you close or reload a window while one is waiting for approval, the chat shows as interrupted, and the next Band start shows you one notification that the agent was waiting when Band reloaded, so a pending approval is never silently dropped. That reload notification follows the agent's short (five-second) cross-window lock: two cases deliberately skip it — reopening a crashed window within about five seconds of the crash, while the old lock still reads as live (press Start; the agent's next request then notifies you normally), and any window while another window currently hosts that agent, because that window has already told you.

Other windows signed into the same Band account never show approval notifications; only the hosting window can act on the approval. Opening the room in one of those windows shows the agent as interrupted or stale, never as a shared live approval, and its Start/Approve controls cannot act on the other window's session.

Turn these notifications off with Band › Notifications: Approvals (band.notifications.approvals) and Band › Notifications: Mentions (band.notifications.mentions); both are on by default. Each suppresses only the VS Code notification — in-Band cards, unread counts, and the agents' work are unchanged. They are stored for this machine and shared by all its Band windows, take effect on the next notification without a reload, and a non-on/off value is treated as off.

Attach files

The room composer carries a toolbar under its text field, with mention and attach buttons on the left and send on the right. When your Band deployment serves file transfer, the attach button uploads files to the room. Otherwise, it copies each picked file into the extension's global storage and adds a Markdown link to your draft whose destination is the local file URL wrapped in angle brackets. These copies are never deleted automatically and anyone on this machine who can access that path can read them.

The upload button opens VS Code’s own file dialog. Band reads the picked files in the extension host and uploads them under your signed-in session — the webview never sees your credentials or the file bytes. Staged files show as composer chips while they upload, and as message chips after send. Click a message chip to save a copy through VS Code’s save dialog. Image messages can show a thumbnail from the extension’s thumbnail cache, not from your project tree.

Uploads carry at most 10 files per message, 100 MB each. A file whose upload fails keeps its chip with a retry button. Local-link picks carry at most 8 files at a time and apply the same 100 MB per-file ceiling; they appear as draft text rather than composer chips.

A file is uploaded to the room as soon as you attach it, before you send the message — that is what puts it behind a chip with a size. Removing a chip keeps the file off your message and deletes Band's local copy, but it does not delete the uploaded file from the room, so anyone with access to the room's files can still see it. Attach deliberately. The Chats composer never attaches files.

Dragging files onto the panel and pasting them into the composer are deliberately not supported: while an OS file drag is over the VS Code window, the workbench disables pointer events on webview iframes, so the drop never reaches Band.

Spelling assistance in the composer

The Band composer underlines likely misspellings in what you are about to send and can offer replacements for them. It is on by default.

Put the caret in an underlined word and press Ctrl+. (Cmd+. on macOS) to see replacements for that occurrence; picking one changes only that occurrence. Ignore for this draft in the same list stops that word being marked for the rest of the draft without remembering it later. Alt+F7 moves to the next misspelling and Alt+Shift+F7 to the previous one, and the composer exposes the count and the current word as a spelling status region that screen readers announce.

Checking runs on your machine through the macOS spelling service, in a helper process Band starts for the open composer. No dictionary is bundled, the helper talks only to the local macOS spell API, and drafts, words, and suggestions are never sent to Band, written to a log, or kept once the draft is gone.

Two limits are worth knowing. This is local macOS only: in a Remote-SSH or dev container window, and on Windows or Linux, the setting has no effect, no underlines appear, and Band adds no status message about it. And only prose is checked — mention chips, URLs, code (inline and fenced), file paths, identifiers such as camelCase, tokens containing digits, and lines starting with /, -> or => are left alone; a draft too large to check (over 512 lines, or roughly 20 000 characters) is left unmarked rather than partly marked.

Turn it off with Band › Spelling: Typo Detection (band.spelling.typoDetection). The underlines disappear and the checker stops, and your draft is untouched either way.

Connect external tools with MCP

Model Context Protocol (MCP) lets agents use tools from external services alongside their local coding tools—for example, to work with issue trackers or retrieve project information.

Band's MCP authorization commands support Oh My Pi (OMP) sessions. First configure the server in an MCP configuration that OMP imports, such as your project's .omp/mcp.json. These commands manage authorization for an eligible configured server; they do not add a server to your configuration.

Open the Command Palette and use:

• Band: Authorize MCP Server... — enter the server's resource URL and complete browser sign-in if requested. Band stores the authorization for use when you next start an OMP agent session.
• Band: Remove MCP Server Authorization... — choose a server to remove Band's stored authorization. This does not revoke the token at the service itself; revoke access with the provider if you need to invalidate it there.

Start a new OMP agent session after changing authorization; these commands do not modify running sessions. Claude Code and Codex CLI use their own MCP configuration and authentication.

Your data and permissions

• Your sign-in stays separate from your agents. Band authenticates you through your browser and keeps the resulting session in VS Code Secret Storage. The extension does not pass your credentials to local agent processes.
• Coding tools run locally. They work in the project folder you authorize, with file and command access determined by the permission mode you choose.
• Room activity is shared through Band. Messages and session activity are sent to the Band service so room participants can collaborate. Running a coding tool locally does not mean the conversation stays on your machine.
• Tool reporting is opt-in. With Band › Tool Reporting: Enabled on, your agents' tool calls and results are shared with everyone in their rooms, starting on the next turn. It is off by default, applies to all rooms on this machine, and cannot recall reports already sent. See the Operator Guide's Tool reporting section for what is shared and redacted.
• Spelling checks stay local. Composer spelling runs against the macOS spelling service on this machine and nothing about it — your draft, the words checked, or the replacements offered — is sent to Band or written to a log.

Need help?

An agent won't start

Check these first:

1. Open exactly one local project folder in VS Code and make sure you trust it.
2. Make sure the selected coding tool is installed, signed in, and available on your PATH.
3. Check the error shown in the Band sidebar. Band starts an agent when the tool's required capabilities work, so the message names what actually failed — a missing binary, a capability the installed tool does not provide, or a sign-in the tool still needs.

For more details, open View → Output in VS Code and select Band from the output channel dropdown.

You can't sign in

If Sign In doesn't open a browser, browser sign-in only works in a local desktop VS Code window — it is unavailable in a Remote-SSH, WSL, dev container, or web (vscode.dev) window. If the browser opens but sign-in doesn't complete, check the sidebar's error text (it names the specific reason — denied, unreachable server, or a misconfigured deployment) and select Retry. For a custom or on-prem deployment, confirm the server URL first.

Spelling underlines don't appear

The composer only marks what it can check. In order:

1. Band › Spelling: Typo Detection (band.spelling.typoDetection) is on by default; check it wasn't turned off.
2. The window has to be a local macOS window. In a Remote-SSH or dev container window, and on Windows or Linux, checking is deliberately off and no message is shown about it.
3. If your draft is over 512 lines, or roughly 20 000 characters, the whole draft is left unmarked rather than partly marked — split the message.
4. Something that isn't prose is never marked: code, URLs, mention chips, file paths, camelCase identifiers, and tokens containing digits.
5. After three terminal failures in a row the extension stops checking for the session. Toggling Band › Spelling: Typo Detection off and on again clears that and starts a fresh helper process.

Still stuck?

Contact support@band.ai.

License

Band for VS Code is proprietary software. See the license included with the extension for the applicable terms.