Skip to content
stoneforge

Installation

Prerequisites

  • Node.js 18 or later (or Bun, any recent version)
  • Git 2.30 or later (worktree support required)

Install

Terminal window
npm install -g @stoneforge/smithy

Initialize your project

  1. Navigate to a git repository:

    Terminal window
    cd your-project

  2. Initialize Stoneforge:

    Terminal window
    sf init

What sf init creates

The sf init command creates a .stoneforge/ directory at the root of your project:

your-project/
├── AGENTS.md              # Context file for AI coding agents (if no AGENTS.md or CLAUDE.md exists)
└── .stoneforge/
    ├── config.yaml        # Project configuration
    ├── stoneforge.db      # SQLite database (local cache)
    ├── .gitignore         # Ignores db and local-only files
    └── playbooks/         # Workflow templates

Agent providers

Stoneforge orchestrates agents — it doesn’t include an AI model itself. You need at least one agent provider CLI installed and working before starting Stoneforge.

Install a provider

Terminal window
npm install -g @anthropic-ai/claude-code

Then authenticate:

Terminal window
claude

Requires a Claude Pro, Max, or Team plan, or an Anthropic API key. See the Claude Code docs for setup details.

Set the provider per-agent

The default provider is Claude Code. To use a different provider, set it at registration:

Terminal window
sf agent register Worker1 --role worker --provider claude-code
sf agent register Worker2 --role worker --provider opencode
sf agent register Worker3 --role worker --provider codex

You can mix providers in the same workspace — for example, use Claude Code for your Director and Codex for workers.

Verify installation

Run sf doctor to check that everything is configured correctly:

sf doctor

System Health Check

[OK] workspace: Workspace found at /Users/you/my-project/.stoneforge

[OK] database: Database found at /Users/you/my-project/.stoneforge/stoneforge.db

[OK] connection: Database connection successful

[OK] schema_version: Schema is at version 9 (up to date)

[OK] schema_tables: All expected tables present

[OK] integrity: Database integrity check passed

[OK] foreign_keys: Foreign key constraints satisfied

[OK] blocked_cache: Blocked cache is consistent

[OK] storage: Database size: 256 KB

Summary: 9 ok, 0 warnings, 0 errors

System is healthy.

Configuration

The .stoneforge/config.yaml file controls project-level settings:

Parameter Type Default Description
actor string — Default actor name or ID for operations.
base_branch string — Base branch for merge targets (e.g., master or main). Auto-detected from git if omitted.
database string stoneforge.db SQLite database filename, relative to .stoneforge/.
sync.auto_export boolean true Automatically export mutations to JSONL files.
sync.export_debounce number 300000 Debounce interval in ms for batching exports (5 minutes).
sync.elements_file string elements.jsonl JSONL filename for exported elements.
sync.dependencies_file string dependencies.jsonl JSONL filename for exported dependencies.
identity.mode string soft Identity verification mode: soft (name-based), cryptographic (Ed25519 signatures), or hybrid (accepts both).
identity.time_tolerance number 300000 Time tolerance in ms for signature expiry in cryptographic mode (5 minutes).
playbooks.paths string[] [".stoneforge/playbooks", "~/.stoneforge/playbooks"] Search paths for playbook definitions.
tombstone.ttl number 2592000000 Time-to-live in ms for soft-deleted records before permanent removal (30 days).
tombstone.min_ttl number 604800000 Minimum allowed TTL in ms for tombstones (7 days).
plugins.packages string[] [] NPM package names that export CLI plugins.

Next steps

Quick Start Go from zero to your first multi-agent orchestration
Stoneforge Overview Learn more about how Stoneforge fits into your development workflow