How the Pack Cockpit Dashboard Functions in SwarmForge: Architecture and Implementation

The Pack Cockpit Dashboard is a local web interface that renders real-time project state by monitoring filesystem hand-off directories and exposing agent activities through a Babashka Clojure HTTP server binding to a dynamic localhost port.

The Pack Cockpit Dashboard serves as the central control interface for SwarmForge operations, transforming on-disk project artifacts into an interactive browser-based control panel. According to the unclebob/swarm-forge source code, this dashboard requires no external database or cloud services, instead reading directly from local hand-off directories to display project swim-lanes, agent status, and approval queues in real time.

Core Architecture and Entry Points

The dashboard architecture follows a layered design with shell script wrappers delegating to Clojure implementations that manage HTTP serving and state aggregation.

The Launcher Scripts

The entry point resides in swarmforge/scripts/pack_web.sh, a thin Bourne shell wrapper that forwards all arguments to the Babashka script swarmforge/scripts/pack_web.bb. This abstraction allows the host environment to launch the dashboard without hardcoding Babashka invocation details across the codebase.

The main server implementation in pack_web.bb initializes an http-kit server (invoking http/run-server around line 1500) and registers REST endpoints for project management, task creation, and hand-off approvals. This single file contains the full HTTP server logic, JSON UI generation, and filesystem polling mechanisms.

Configuration and Role Definitions

Before the server accepts connections, it reads swarmforge/swarmforge.conf to determine which roles (tmux windows) belong to the current pack. This configuration file declares the agent composition and pane layout, enabling the dashboard to know precisely which processes to monitor and which hand-off directories to scan for state changes.

Startup Sequence and Workspace Preparation

Dashboard initialization occurs automatically when executing the ./swarm host script, which orchestrates filesystem preparation before launching the web server.

Host Initialization and URL Generation

Running ./swarm triggers the following sequence:

1. Prints a Dashboard: URL to stdout (e.g., http://localhost:12345)
2. Persists this URL to .swarmforge/dashboard-url for programmatic access
3. Executes pack_web.sh --serve <forge-root> as a background process

The server binds to a random free port unless overridden via the --port command-line argument passed through the wrapper chain.

Filesystem State Preparation

Prior to HTTP server startup, the host invokes prepare-workspace! → prepare-worktrees! → prepare-handoff-dirs! from the core SwarmForge logic. These functions create the necessary directory structure under each role's .swarmforge tree, including outbox/, inbox/, and notify/ directories that serve as the single source of truth for the dashboard's read-only view.

Data Model and API Endpoints

The dashboard exposes a REST API that translates filesystem artifacts into JSON models consumed by the front-end interface.

Board State and Task Lanes

The GET /board endpoint delegates to swarmforge/scripts/pack_board.bb, which implements the board-generation logic. This helper script:

• Reads each project's hand-off state from inbox/ and outbox/ directories
• Returns a tabular view containing lanes, list, and master-lane arrays
• Maps filesystem entries to cards displayed in the UI's swim-lane visualization

The GET /attention endpoint scans the notify/ directory for pending human gates, including approval requests and clarification prompts that require operator intervention before agents proceed.

Live Agent Monitoring

To display current agent activities, the dashboard polls GET /status/:role endpoints that invoke functions like live-pane-text and im-status within pack_web.bb. These utilities read the live tmux pane text for the specified role and extract the last two status sentences using im-status-lines, deliberately filtering out tool traces and mail banners to show only meaningful progress updates.

User Interactions and State Changes

While primarily read-only, the dashboard accepts POST requests that modify filesystem state to trigger agent behaviors.

Project Lifecycle Management

Clicking New Project in the UI triggers POST /new-project, which:

• Creates a new directory under projects/
• Copies files from the selected pack template
• Writes the initial mission.md document
• Launches the pack's agents in separate tmux sessions

Task Creation and Approval Workflows

The New Task button issues POST /new-task, calling the handle-new-task function in pack_web.bb. This implementation constructs a task payload and invokes inject-master! to write a hand-off note (with type: note) into the lieutenant pane's outbox, immediately surfacing as a new card on the board.

For human-in-the-loop gates, the POST /approval/:id endpoint processes Approve or Reject actions by moving cards between directories or updating their metadata status through the approve and reject logic defined in pack_web.bb.

Real-time Updates and Event Streaming

The dashboard maintains synchronization with agent activities through filesystem watching rather than direct process communication. The server utilizes fs/watch-style polling on hand-off directories and pushes changes to connected browsers via Server-Sent Events. When an agent writes new output to its tmux pane, the im-status-lines function extracts the relevant status text and broadcasts updates to the corresponding board card, ensuring the interface reflects ground-truth without requiring manual refreshes.

Code Examples

Start the host and dashboard with automatic browser opening:

# Start the host and the dashboard (default opens the browser)

$ ./swarm
Dashboard: http://localhost:12345  # URL also written to .swarmforge/dashboard-url

Create a new project programmatically via the REST API:

# Create a new project via the UI (alternatively: curl)

$ curl -X POST "$(cat .swarmforge/dashboard-url)/new-project" \
    -d 'name=my‑app&pack=two‑pack&mission=Add%20a%20CLI%20tool'

The internal handler for task creation in pack_web.bb:

;; Inside pack_web.bb – the handler that creates a new task
(defn handle-new-task [root name text]
  (let [payload (task-payload name text)]
    (inject-master! root payload)          ; injects a note into the lieutenant pane
    (println "Created task" name)))

Debug the dashboard independently of the host:

# Manually start the dashboard without the host (useful for debugging)

$ pack_web.sh --serve /path/to/forge --port 8080

# Then open http://localhost:8080 in a browser.

Extract live agent status for display on board cards:

;; Example of extracting the status line for a role (used by the UI)
(im-status "coder" (slurp "/path/to/.swarmforge/roles.tsv") "codex")
;; → "I'm writing the new endpoint…"   ; displayed on the board card

Summary

• The Pack Cockpit Dashboard operates as a local HTTP server implemented in pack_web.bb, launched by the pack_web.sh wrapper script.
• It maintains a read-only view of the filesystem, reading hand-off directories (inbox/, outbox/, notify/) to render project boards and agent status.
• The architecture uses REST endpoints (/board, /attention, /status/:role) to serve JSON data and Server-Sent Events for live updates without page refreshes.
• User actions like creating projects or approving tasks result in filesystem mutations that agents detect and process through the standard hand-off protocol.
• All configuration originates from swarmforge.conf, which defines the roles and pane layouts monitored by the dashboard.

Frequently Asked Questions

How do I access the Pack Cockpit Dashboard if the automatic browser launch fails?

The ./swarm script writes the dashboard URL to .swarmforge/dashboard-url in the forge root directory. You can retrieve the active URL by running cat .swarmforge/dashboard-url and navigating to that address manually in any browser on the local machine.

Can the dashboard run on a fixed port instead of a random ephemeral port?

Yes. When starting the dashboard manually via pack_web.sh --serve, append the --port argument with your desired port number (e.g., pack_web.sh --serve /path/to/forge --port 8080). This overrides the default behavior of binding to the first available random port.

What happens to active agents when I click the Teardown button in the UI?

Clicking Teardown sends a request that terminates every tmux session associated with the pack, stops the lieutenant agent, removes the pack_web.pid file, and displays Swarm disconnected in the interface. Notably, this operation leaves all project directories intact on disk; it only stops the running processes and the dashboard server.

How does the dashboard distinguish between meaningful agent output and system noise?

The im-status-lines function in pack_web.bb filters raw tmux pane text by ignoring predefined patterns such as tool execution traces and mail banners. It extracts only the final two sentences of status output, ensuring that the dashboard displays concise, human-readable progress updates rather than verbose log dumps.

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