Name: Stoneforge
Author: Stoneforge

How Stoneforge orchestrates Claude Code

Claude Code is Anthropic’s AI coding agent for the terminal. It reads your codebase, edits files, runs commands, and commits code. As a Claude code agent, a single session typically handles one task at a time, though Anthropic’s experimental Agent Teams feature can coordinate multiple sessions within Claude Code itself.

Stoneforge takes a different approach to multi-agent coordination. Rather than running within the Claude AI coding agent, it wraps Claude Code sessions from the outside, dispatching tasks across multiple agents in isolated git worktrees and managing the merge process.

Parallel task execution with Claude Code

You define the work, and Stoneforge dispatches it to multiple Claude Code agent sessions running in parallel:

# Create a plan with multiple tasks
sf plan create --title "Sprint 14"

sf task create --title "Add user invitation API" --plan "Sprint 14"
sf task create --title "Build notification system" --plan "Sprint 14"
sf task create --title "Refactor auth middleware" --plan "Sprint 14"
sf task create --title "Add integration tests for billing" --plan "Sprint 14"

# Start orchestration
sf serve

Each task gets its own Claude Code session and its own git worktree. One agent builds the invitation API while another works on notifications, independently and in parallel.

Context management across sessions

Claude Code has a 200k token context window, and performance starts to degrade well before that limit. Stoneforge manages this by triggering handoffs when an agent’s context gets full:

At ~140k tokens, the agent creates a structured handoff capturing progress and remaining work
A fresh Claude Code session picks up with the handoff context
Committed and pushed work carries over automatically

Long tasks that would exhaust a single session’s context get split across multiple sessions. Some context is inevitably lost in the handoff, but the structured format preserves the important parts.

Merge coordination for Claude Code agents

Running multiple Claude AI coding agents in parallel means dealing with merge conflicts. Stoneforge’s Steward agent handles this:

Runs your test suite against each completed branch
Detects merge conflicts early
Resolves straightforward conflicts automatically
Creates merge requests with change summaries for human review
Sequences merges using the dependency graph to reduce conflicts

Role-based orchestration

Stoneforge assigns Claude Code sessions to specialized roles:

Director creates plans, breaks down work, and answers questions from workers
Workers execute tasks, write code, commit and push
Stewards review merge requests, run checks, and merge approved work
Daemon dispatches tasks to available workers automatically

Each role gets tailored system prompts and tool access. Workers can’t merge their own code, and stewards don’t write features. This separation keeps each session focused.

Failure recovery

If a Claude Code session crashes or loses connection, Stoneforge detects it and re-dispatches the task:

Committed and pushed work is preserved in the git worktree
The task gets marked for re-dispatch
A fresh Claude Code session picks up with the task context
Work resumes from the last committed state

Uncommitted work within a crashed session is lost, so Stoneforge’s system prompts instruct agents to commit and push frequently.

Getting started

Install Stoneforge and configure it to use Claude Code:

# Install Stoneforge
npm install -g @stoneforge/cli

# Initialize in your project
sf init

# Start the orchestrator
sf serve

The default configuration works with Claude Code out of the box. Adjust agent count, model selection, and merge behavior in .stoneforge/config.yaml.

Learn more

Best AI Coding Agents in 2026 — see how Claude Code compares to other AI coding agents
Run Multiple AI Coding Agents in Parallel — step-by-step guide to parallel agent workflows
Claude Code Teams vs Self-Hosted — compare managed vs self-hosted Claude Code setups

Configuration

.stoneforge/config.yaml

# .stoneforge/config.yaml
orchestrator:
  agent: claude-code
  maxConcurrent: 6
  worktreeIsolation: true

agents:
  worker:
    provider: claude-code
    model: claude-sonnet-4-20250514
    maxSessionTokens: 200000
  steward:
    provider: claude-code
    model: claude-sonnet-4-20250514
    autoMerge: true
    runChecks: true
  director:
    provider: claude-code
    model: claude-sonnet-4-20250514

Claude Code alone vs. with Stoneforge

Claude Code alone	With Stoneforge
Single agent, single task at a time	Multiple agents working on different tasks simultaneously
Manual context management across sessions	Automatic context handoff when agents hit token limits
One git branch, sequential commits	Isolated worktrees per agent, parallel branches
Manual code review and merging	Steward agent reviews, tests, and merges automatically
Session state lost on crash	Re-dispatches tasks from last committed state on failure
You manage task ordering	Dependency-aware dispatch with priority queues
Agent Teams (experimental) for multi-session coordination	Role-based orchestration: director plans, workers execute, stewards merge