User Guide

Dashboard Overview

The main dashboard shows:

• Team cards -- Each active agent team with status (running, idle, completed, errored)
• Quick stats -- Total agents running, tasks completed today, pending tasks
• Recent activity -- Last 20 events across all teams (agents spawned, tasks completed, errors)
• New Team button -- Launches the team creation wizard

Color-coded status indicators:

• Green: Agent is actively working
• Amber: Agent is idle or waiting for input
• Red: Agent encountered an error
• Gray: Agent or task is completed

Creating a Team

Click "New Team" to launch the team creation wizard. The wizard has four steps.

Step 1: Project Setup

Choose your working directory for the team. This is where agents will operate.

• Select Directory -- Uses the native Windows folder picker
• Team Name -- Auto-populated from the directory name, editable
• Execution Mode -- Set to "tmux" for v0.1 (SDK mode coming in v0.2)

Step 2: Agent Roles

Define the agent roles that will make up your team. You can add 1-6 agents.

For each agent:

• Name -- Unique identifier (e.g., "Frontend Specialist")
• Description -- What this agent does
• Model Tier -- Haiku (fast/cheap), Sonnet (balanced), or Opus (powerful)
• System Prompt -- Optional custom instructions (leave blank to use defaults)

Quick templates available:

• Full-stack feature (4 agents: Frontend, Backend, DevOps, QA)
• Code review (3 agents: Reviewer, Commenter, Approver)
• Research sprint (2 agents: Researcher, Analyst)

You can also add agents manually after the team launches.

Step 3: Governance Rules

Set permission boundaries that apply to all agents in this team. These are enforced via Claude Code's existing permission system.

Toggles:

• Can create new files -- Allow agents to create files in the working directory
• Can run shell commands -- Allow agents to execute CLI commands
• Can push to git -- Allow agents to commit and push changes
• Max turns before check-in -- Slider (5-50 turns) before agent must wait for human approval

These rules are set at team creation and cannot be changed mid-run. To modify governance, end the team and create a new one.

Step 4: Review and Launch

Review your configuration and click "Launch Team". The dashboard navigates to the live monitor for this team.

Live Monitoring

The live monitor is where you watch agents work. It has two main sections.

Agent Activity (Left panel)

Each agent gets a card showing:

• Agent name and role
• Current status (working, idle, waiting, completed, errored)
• Model tier (Haiku, Sonnet, Opus)
• Last 50 lines of terminal output
• "Send message" input field

Click the agent card to expand/collapse the terminal output. The output updates in real-time via WebSocket.

Sending a message to an agent: Type in the "Send message" field and press Enter. The message is sent to that agent's tmux pane as if you typed it.

Task Board (Right panel)

Shows all tasks for this team:

• Task title
• Assigned agent (if any)
• Status (pending, claimed, in-progress, review, completed, blocked)

Click a task to view full details and description. You can manually mark a task complete if the agent forgot.

Team Controls (Bottom bar)

• Pause all -- Send Ctrl+C interrupt to all agents (non-destructive)
• Resume -- Send resume signal to paused agents
• Add agent -- Spawn an additional agent mid-run
• End team -- Graceful shutdown (agents finish current task, then terminate)
• Kill team -- Immediate termination of all sessions

Task Management

Tasks can be created by agents or by you manually. Each task has:

• Title and description
• Assigned agent (or unassigned)
• Status: pending, claimed, in-progress, review, completed, blocked
• Parent task (for task hierarchies)
• Created by (agent or user)
• Timestamps

Tasks are stored in ~/.claude/tasks/{team-name}/ as JSON files. The dashboard reads and monitors these files for changes.

You can manually update task status from the task board. This is useful if an agent completes a task but forgets to update the status.

Workflow Templates

Templates let you save and reuse team configurations.

Save a template

During team creation (Step 4: Review), click "Save as template". Templates store:

• Agent roles and model tiers
• Governance rules
• System prompts

Use a template

On the Templates page, click "Launch from template" to pre-fill the wizard with the template's settings.

Import/Export

Templates are JSON files. You can:

• Export -- Click "Export" on a template to download the JSON
• Import -- Click "Import template" and upload a JSON file

Share templates with teammates via email, Git, or your team repo.

Token and Tool Usage

The dashboard tracks token consumption and tool usage for cost visibility.

Token tracking

• Input and output tokens per agent response
• Cache read and creation tokens (if using prompt caching)
• Estimated cost in USD (based on current Claude pricing)
• View per agent or aggregate for the whole team

Navigate to the team's stats page to see token usage charts.

Tool usage

• All tool invocations are logged (both Claude built-ins and MCP tools)
• Tool name, input summary, and timestamp
• Identify which agents use which tools most frequently

MCP Server Discovery

BumbaClaude automatically discovers MCP servers available to agents.

• Detected from agent output streams
• Listed in the team settings
• Shows server name, status, and configuration source
• You can manually add servers if auto-discovery misses one

Scheduled Tasks

Create recurring tasks that run on a schedule (e.g., daily report, weekly cleanup).

Create a schedule

In the team settings, click "New schedule":

• Name -- Description (e.g., "Daily regression tests")
• Type -- Interval (milliseconds) or Cron expression
• Message -- The task message to send to the agent
• Agent -- Which agent runs the task
• Enabled -- Toggle on/off

Examples:

• Interval: 86400000 (24 hours)
• Cron: 0 9 * * MON-FRI (9 AM weekdays)

View schedule history

Click on a schedule to see when it last ran and how many times it's executed.

Context Files

BumbaClaude discovers and displays context files (documentation, examples) available to agents.

• Auto-discovery from the project directory
• Searchable file list
• Preview file contents
• Specify additional context file paths in governance settings

Agents can reference these files in their system prompts or ask you to share them.

Audit Log

The audit log is a complete event history for each team.

Navigate to a team's audit page to see:

• Agent spawned (name, model, role)
• Task created / claimed / completed / blocked
• Message sent (to/from agent)
• File modified (path and agent)
• Command executed (command string and agent)
• Error occurred (stack trace if captured)
• Team ended (reason)

Filter by:

• Agent
• Event type
• Time range

All events are timestamped and stored in the SQLite database.

Desktop App Features (Electron)

The desktop app adds native OS features on top of the web dashboard.

System Tray

Right-click the tray icon for options:

• Show/Hide window
• Active teams count
• Quit application

The tray icon changes color based on agent status:

• Green: All agents healthy
• Amber: Agents idle or waiting
• Red: Agent error
• Gray: No active teams

Notifications

Native Windows toast notifications appear for:

• Agent completed a task
• Agent encountered an error
• Agent waiting for human input
• Governance limit reached

Click a notification to open the app and navigate to the relevant team/agent.

Global Hotkey

Press Ctrl+Shift+B (default, configurable) to show/hide the window from anywhere.

Close to Tray

Click the X button to minimize to the tray (agents keep running). Close from the tray menu to fully quit.

Auto-Update

BumbaClaude checks for updates on launch and periodically. When an update is available:

• A banner appears in the app
• Click "Install update" to download and install
• App restarts when the download is complete