Quick Start

This guide walks you through a complete multi-agent workflow — from installing Stoneforge to watching agents execute tasks in parallel.

From zero to orchestrating

Install the Stoneforge CLI
Terminal window
```
npm install -g @stoneforge/smithy
```
Initialize a workspace in your project
Terminal window
```
cd your-project
sf init
```
Start the server and web dashboard
Terminal window
```
sf serve
```
The dashboard opens at http://localhost:3457.

Register a Director

sf agent register director --role director

Start the Director
Terminal window
```
sf agent start <id>
```
Use the ID printed by the previous command. You can also start the Director from the Director Panel in the dashboard’s right sidebar.

Register workers

sf agent register e-worker-1 --role worker
sf agent register e-worker-2 --role worker

Register a Merge Steward

sf agent register m-steward-1 --role steward --focus merge

Give the Director your goal

Open the Director Panel in the dashboard sidebar and describe what you want to build. The Director will break it into tasks with priorities and dependencies.
Watch it work
- Activity page — live agent output from all running agents
- Tasks page — task statuses, assignments, and progress
- Merge Requests page — completed work waiting for or passing merge review

Behind the scenes, Stoneforge executed a coordinated workflow:

The Director decomposed your goal into tasks with priorities and dependencies
The dispatch daemon detected ready (unblocked, unassigned) tasks and assigned them to idle workers
Each worker spawned in an isolated git worktree (agent/{worker-name}/{task-id}-{slug})
Workers executed their tasks, committed, and pushed their branches
Completed tasks created merge requests for the merge steward
The merge steward ran tests, squash-merged passing branches, and created fix tasks for failures
The loop repeated until all tasks were closed

Core Concepts Understand the building blocks of Stoneforge

First Multi-Agent Project A deeper walkthrough with real code