# SwarmForge Dashboard Components: A Complete UI Architecture Guide

> Explore the eight essential SwarmForge dashboard components including header, error bar, attention area, main board, queues, chat, and modal dialogs. Understand the UI architecture.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: architecture
- Published: 2026-08-29

---

**The SwarmForge dashboard consists of eight core components: a pack identity header with global controls, an error bar, an attention area for human-gate approvals and clarifications, a main board with project bands and swimlane cards, a work queue rail, a master chat rail, modal dialogs for project and task creation, and supporting server-side scripts written in Clojure.**

The SwarmForge dashboard (also called the "pack cockpit") is a single-page web interface for visualizing and controlling AI agent swarms. All UI elements live in **[`swarmforge/scripts/pack/dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html)** and are powered by the ClojureScript server in **`swarmforge/scripts/pack_web.bb`**. This guide breaks down each SwarmForge dashboard component and shows you how they connect to the underlying orchestration layer.

## Header: Pack Identity and Global Controls

The top bar (lines 34-41 in [`dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/dashboard.html)) provides context and swarm-level actions.

| Element | ID | Function |
|---------|-----|----------|
| **Pack title** | `#pack-title` | Displays the running pack name from the `manifest` file |
| **Live indicator** | `#pack-meta .dot` | Green dot when dashboard is connected; toggled via `dashboard-url` file |
| **Teardown button** | `#teardown-btn` | Kills all projects, lieutenant, tmux sessions, and the dashboard itself |
| **New Project** | `#btn-new-project` | Opens modal to create projects with name, pack, GitHub repo, and mission |
| **Open Project** | `#btn-open-project` | Dropdown of existing projects under `projects/` directory |
| **New Task** | `#btn-new-task` | Adds task to the *master* lane of current project |

The server populates project lists by scanning the filesystem and reads pack metadata on startup. All button actions route through `./swarm` → `pack_web.bb` endpoints.

## Error Bar

The error display (`<p id="error" class="error">` at line 51) shows red-text feedback when [`pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_dashboard_request.sh) calls fail. This includes malformed arguments or filesystem permission errors.

## Attention Area: Human-Gate Queue

Lines 53-58 define the critical human-in-the-loop interface where operators intervene in agent workflows.

**Two subsections handle different request types:**

- **`#attention-approvals`** — *Approval* handoffs requiring explicit sign-off (e.g., specifiers awaiting operator confirmation)
- **`#attention-clarifications`** — *Request clarification* handoffs where agents ask questions

The server polls `.swarmforge/dashboard/` directories across all projects and injects rows dynamically. Operators respond by typing text and pressing **Enter**, which invokes:

```bash
pack_dashboard_request.sh answer <request-id> <answer-file>

```

Request files with `type: approval` or `type: clarification` trigger these UI elements automatically.

## Main Board: Project Bands and Cards

The kanban-style workspace (lines 62-64 with dynamic templates) visualizes all active projects.

Each **project band** contains:

| Part | Description |
|------|-------------|
| **Project header** (`.project-header`) | Project name with "New Task" and "Close" buttons |
| **Swimlanes** | Columns per role (*coder*, *refactorer*, etc.) plus **Done** |
| **Cards** (`.card`) | Tasks showing title, status line, audit-count badge, action buttons |

Card positioning is computed by the `lanes` and `task-entry` functions in `pack_web.bb`. Cards move automatically when handoff files are processed in `.swarmforge/dashboard/requests/`.

## Work Queue Rail

The right-hand panel (lines 68-76, `#work-rows` in `<table class="work">`) lists pending handoffs across all projects:

| Column | Data Source |
|--------|-------------|
| **Task** | `task-entry :name` from server |
| **Role** | Destination agent role |
| **State** | Status icon from handoff file state |
| **Age** | Relative timestamp from file creation |

Refreshed every few seconds from `.swarmforge/dashboard/requests/pending`. This gives operators a cross-project view of queue depth.

## Master Chat Rail

The bottom-right interface (lines 81-89) communicates with the **lieutenant** — the top-level swarm orchestrator.

- **`#chat-history`** — Chronological message log with the lieutenant
- **`#chat-input`** — Textarea for operator follow-ups; **Enter** submits via `pack_dashboard_request.sh answer`
- **`#btn-open-master-rail`** — Opens live tmux pane for debugging the lieutenant directly

## Modal Dialogs

Three overlay dialogs handle complex interactions:

| Dialog | ID | Purpose |
|--------|-----|---------|
| **Reject Layer** | `#reject-layer` | Handles rejected tasks with options to delete, retry, or accept unchanged (`#rt-delete`, `#rt-retry`, `#rt-accept`) |
| **New Project Layer** | `#new-project-layer` | Collects: name (`#np-name`), GitHub repo (`#np-github`), mission (`#np-mission`), pack selection (`#np-packs`), confirmation (`#np-conf`) |
| **New Task Layer** | `#new-task-layer` | Collects task name (`#nt-name`) and description (`#nt-text`) |

All are `<div class="float-layer">` elements toggled via CSS `open` class by client JavaScript.

## Supporting Server Scripts

Three Clojure files power the dashboard backend:

### `pack_web.bb` — HTTP Server

Core functions driving the SwarmForge dashboard:

| Function | Responsibility |
|----------|---------------|
| `dashboard-page` | Serves static [`dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/dashboard.html) |
| `dashboard-state` | Aggregates pending/ready tasks from filesystem |
| `write-dashboard-url!` | Creates `.swarmforge/dashboard-url` for live indicator |

### `pack_dashboard_request.bb` — CLI Facade

Implements subcommands the UI calls via `fetch('/api/...')`:

- `create` — new projects or tasks
- `list` — enumerate projects or pending requests
- `answer` — respond to clarifications
- `approve` / `reject` — handoff decisions
- `clarify` — initiate clarification flow

### `forge.bb` — Shared Library

Loaded by `pack_web.bb`. Provides tmux control, filesystem operations, and handoff protocol utilities.

## Command Examples for Dashboard Actions

These commands mirror what the UI executes — useful for automation or testing:

### Create a New Project

```bash
./swarmforge/scripts/pack_dashboard_request.sh create \
  --root /tmp/example \
  --name my-app \
  --pack four-pack \
  --mission "Demo of a four-pack project"

```

Creates `projects/my-app/`, writes `dashboard-url`, and launches browser.

### Add a Task to Master Lane

```bash
./swarmforge/scripts/pack_dashboard_request.sh create \
  --root /tmp/example \
  --task-name "initial-setup" \
  --task-text "Generate the project skeleton and run tests."

```

Appears instantly in Board, Work Queue, and Attention areas.

### Respond to Clarification

```bash
./swarmforge/scripts/pack_dashboard_request.sh answer 23 ./tmp/answer.txt

```

Injects answer text into the waiting agent's tmux pane.

### Approve or Reject Handoff

```bash

# Approve request 7

./swarmforge/scripts/pack_dashboard_request.sh approve 7

# Reject with comment

./swarmforge/scripts/pack_dashboard_request.sh reject 7 "Need more details"

```

## Key Source Files Reference

| File | Location | Role |
|------|----------|------|
| [`dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/dashboard.html) | `swarmforge/scripts/pack/` | Static UI markup for all components |
| `pack_web.bb` | `swarmforge/scripts/` | HTTP server and JSON API |
| `pack_dashboard_request.bb` | `swarmforge/scripts/` | CLI interface for UI actions |
| `forge.bb` | `swarmforge/scripts/` | tmux, file, and handoff utilities |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | Repository root | High-level "Pack Cockpit" documentation |

## Summary

- **Header** provides pack identity, live status, and global swarm controls including teardown
- **Attention Area** surfaces approval and clarification requests requiring human intervention
- **Main Board** displays project bands with role-based swimlanes and task cards
- **Work Queue** offers a compact cross-project view of pending handoffs
- **Master Chat** enables direct communication with the lieutenant orchestrator
- **Modals** handle project creation, task addition, and rejection workflows
- **Server scripts** (`pack_web.bb`, `pack_dashboard_request.bb`, `forge.bb`) bridge UI actions to filesystem-based handoff protocol
- All **SwarmForge dashboard components** render from a single HTML file driven by ClojureScript polling and tmux session management

## Frequently Asked Questions

### What file contains the SwarmForge dashboard UI markup?

The static HTML lives in **[`swarmforge/scripts/pack/dashboard.html`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack/dashboard.html)**. Every visual component — header, attention area, board, rails, and modals — is defined here. The server-side logic in `pack_web.bb` injects dynamic content via JavaScript API responses.

### How does the dashboard detect when agents need human approval?

The server polls `.swarmforge/dashboard/` directories for `request` files with `type: approval` or `type: clarification`. These populate the **Attention Area** (`#attention-approvals` and `#attention-clarifications`). Operators respond through the UI, which calls `pack_dashboard_request.sh answer` to complete the handoff.

### Can I interact with the SwarmForge dashboard from the command line?

Yes. The UI ultimately invokes **[`pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_dashboard_request.sh)** with subcommands like `create`, `answer`, `approve`, and `reject`. You can run these directly for automation, testing, or integration with external tools. All commands update the same filesystem state that the dashboard visualizes.

### What happens when I click the Teardown button?

The **Teardown button** (`#teardown-btn`) triggers a cascade through `./swarm` → `pack_web.bb` → `teardown` endpoint. This terminates all tmux sessions, kills running projects, stops the lieutenant, and shuts down the dashboard server itself — effectively stopping the entire swarm.