SwarmForge Dashboard Components: A Complete UI Architecture Guide

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 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) 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 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:

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
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

./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

./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

./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

# 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	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	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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}