Skip to main content
Early-Stage SoftwareStoneforge is experimental software under active development. It’s built for developers already running 3-5 AI coding agents in parallel who need better coordination. Expect high token consumption and autonomous agent behavior without approval gates.

​
What is Stoneforge?

Stoneforge is a multi-agent orchestration platform that solves the coordination problems that emerge when running several AI coding agents in parallel:
  • Merge conflicts — agents editing the same files on the same branch
  • Wasted work — two agents grabbing the same task, or starting work that’s blocked
  • Lost context — when an agent fails mid-task, the next one starts from scratch
  • No visibility — checking each terminal individually to see what’s happening
With Stoneforge, you install the CLI, start the server, and use the web dashboard to direct a team of AI agents. A Director plans the work, Workers execute in isolated git worktrees, Stewards auto-merge and clean up, and a dispatch daemon keeps everyone busy.

Installation

Install the CLI and initialize your first workspace

Quick Start

Get orchestrating agents in under 5 minutes

Examples

Real-world usage patterns and workflows

Architecture

Understand how Stoneforge works under the hood

​
Key Features

  • Director agent breaks down goals into tasks with priorities and dependencies
  • Worker agents execute tasks in parallel, isolated in separate git worktrees
  • Steward agents handle maintenance workflows like merge review and documentation
  • Dispatch daemon auto-assigns ready tasks to idle workers
Each worker operates in its own git worktree (agent/{worker-name}/{task-id}-{slug}) to prevent merge conflicts. Workers commit, push, and create merge requests automatically.
Stewards run tests on completed work, squash-merge on pass, or create fix tasks on failure. Configure test commands, merge strategy (squash/merge), and merge provider (GitHub PR or local).
SQLite provides fast queries with indexes and FTS5 search (the cache). JSONL is the git-tracked, append-only source of truth. State survives restarts and maintains a full audit trail.
Real-time agent output, kanban boards, task dependencies, merge requests, metrics, and an always-available Director panel. Open at http://localhost:3457 after running sf serve.
Supports Claude Code (default), OpenCode, and OpenAI Codex as underlying providers. Set via --provider at agent registration or session start. No API keys in Stoneforge—authentication passes through from the agent harness CLI.

​
How It Works

The orchestration loop coordinates work across agents:
1

You communicate your goal

Tell the Director what you want to accomplish via the Director Panel in the web UI or CLI.
2

Director plans the work

The Director breaks down your goal into a plan with tasks, priorities, and dependencies.
3

Dispatch daemon assigns tasks

The daemon detects ready (unblocked, unassigned) tasks and assigns them to idle workers.
4

Workers execute in parallel

Each worker spawns in an isolated git worktree, executes the task, commits, and pushes.
5

Steward reviews and merges

The merge steward runs tests. On pass: squash-merge. On fail: create a task handoff for another worker.
6

Loop repeats

The daemon continues assigning remaining tasks until the plan is complete.

​
Stoneforge vs. Other Tools

Compared to Claude Code Agent Teams: Stoneforge adds event-sourced persistence (survives restarts), automatic git worktree isolation, dispatch daemon for task assignment, steward-based merge automation, and a web dashboard with real-time visibility. Compared to single agents (Claude Code, Cursor): Parallel execution with coordination, dependency-aware scheduling, and merge review. Compared to background agents (Cursor background agents, Codex): Structured task management, persistent knowledge layer, and merge automation.

​
Architecture Overview

Stoneforge has two main layers:
  • Smithy (@stoneforge/smithy) — the orchestrator. Spawns agents, dispatches tasks, manages sessions, handles worktree isolation and merge review. This is what you install.
  • Quarry (@stoneforge/quarry) — the underlying data SDK. Event-sourced task management, sync, and storage. Used by Smithy internally; also available standalone for custom integrations.

​
Dual Storage Model

┌─────────────────────────────────────────────────────────────┐
│                         SQLite                              │
│  • Fast queries with indexes                                │
│  • Full-text search (FTS5)                                  │
│  • Materialized views (blocked cache)                       │
│  • Ephemeral — rebuilt from JSONL on sync                   │
└────────────────────────────┬────────────────────────────────┘
                             │ sync
┌────────────────────────────▼────────────────────────────────┐
│                         JSONL                               │
│  • Git-tracked, append-only                                 │
│  • Source of truth for all durable data                     │
│  • Human-readable, diff-friendly                            │
│  • Mergeable across branches                                │
└─────────────────────────────────────────────────────────────┘
Key Principle: SQLite is the cache, JSONL is the source of truth.

​
What You Should Know

Before diving in, understand these key points:
Token consumption is high. A typical session can burn through several Claude MAX/Pro subscriptions worth of tokens per week. This is the cost of running a parallel team.
Agents run autonomously. Stoneforge spawns agents with permissions bypassed—no human approval gates before actions. Agents will read, write, execute, and push code without asking.
Things move fast. New capabilities ship weekly, defaults may change, and documentation sometimes lags behind code. Published packages follow semver with changelogs.

​
Ready to Start?

Install Stoneforge

Set up the CLI and initialize a workspace

Quick Start Tutorial

Orchestrate your first team of agents

Build docs developers (and LLMs) love

Get started for freeTalk to us