Claude Code

Claude Code is the default coding agent in Band and offers the deepest integration. It supports cost tracking, session listing, session resume, user input prompts, and skill discovery. Band communicates with Claude Code through the @anthropic-ai/claude-agent-sdk, which provides a streaming event interface for programmatic control.

Prerequisites

1. Install the Claude Code CLI by following the official Anthropic documentation at docs.anthropic.com.
2. Authenticate with your Anthropic API key or Claude Pro/Team subscription.
3. Verify the installation by running claude --version in your terminal.

How Band Integrates via Hooks

Band uses Claude Code's hook system to receive automatic status updates. When you set up Band, it installs hooks into your Claude Code settings file at ~/.claude/settings.json. Five hook events are registered (see apps/web/src/server/services/hooks.ts):

• UserPromptSubmit — Fires when the user submits a prompt. Band marks the workspace as working.
• PreToolUse — Fires before each tool call. Band keeps the workspace working in the general case but flips it to needs attention when the tool is AskUserQuestion or ExitPlanMode.
• PermissionRequest — Fires when the agent requests permission to use an unapproved tool.
• PostToolUse — Fires after each tool call, providing real-time progress updates.
• Stop — Fires when the agent finishes. Band marks the workspace as needs attention.

Each hook runs the command band notify, which reads the JSON payload from stdin, resolves the workspace from the hook's cwd, and posts a status update to the Band server. This is how Band detects agent activity in workspaces where Claude Code is running independently (outside of Band-submitted tasks).

Hooks Configuration

Band manages hooks automatically. From the dashboard, navigate to Settings and click Install Hooks. Band will locate the band CLI binary on your system and write the hook entries into ~/.claude/settings.json. If you already have other hooks configured, Band preserves them and only adds its own entries.

The resulting configuration in settings.json looks like:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "/usr/local/bin/band notify" }] }
    ],
    "PreToolUse": [
      { "hooks": [{ "type": "command", "command": "/usr/local/bin/band notify" }] }
    ],
    "PermissionRequest": [
      { "hooks": [{ "type": "command", "command": "/usr/local/bin/band notify" }] }
    ],
    "PostToolUse": [
      { "hooks": [{ "type": "command", "command": "/usr/local/bin/band notify" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "/usr/local/bin/band notify" }] }
    ]
  }
}

Session Management

Claude Code supports full session management through Band. You can:

• View a list of previous sessions for any workspace, including the session summary, first prompt, git branch, and last modified time.
• Resume a previous session by selecting it from the session list. Band passes the session ID to Claude Code, which picks up where it left off.
• Browse the full message history of any session, including user messages, assistant responses, tool calls, and tool results.

Cost Tracking

Claude Code reports the total cost in USD for each session via the session-result event. Band displays this in the task completion summary, so you can monitor API spend per task. Cost data is available in the task history view for completed tasks.

Configuration Options

The Claude Code adapter accepts these configuration options through Band's settings:

• model — Override the default Claude model (e.g., claude-sonnet-4-20250514).
• executablePath — Path to the Claude Code binary if it is not on your system PATH.
• maxTurns — Maximum number of agentic turns per session (default: 50).