Skip to main content

​
Prerequisites

Before installing Stoneforge, ensure you have:

Node.js 18+

Node.js version 18.0.0 or higher

Bun (Optional)

Any recent version of Bun runtime
Verify your Node.js version:
node --version

​
Install the CLI

Install the Stoneforge CLI globally using npm: 
npm install -g @stoneforge/smithy
The package name is @stoneforge/smithy (the orchestrator). This includes both the sf and stoneforge CLI commands.

​
Verify Installation

Confirm the CLI is installed correctly: 
sf --version
You should see output like: 
@stoneforge/smithy v1.13.0

​
Initialize a Workspace

Navigate to your project directory and initialize Stoneforge: 
cd your-project
sf init

​
What Gets Created

The sf init command creates a .stoneforge/ directory with: 
your-project/
├── .stoneforge/
│   ├── config.yaml           # Default configuration
│   ├── stoneforge.db         # SQLite database (cache)
│   ├── elements.jsonl        # Event-sourced source of truth
│   ├── .gitignore            # Git ignore patterns for DB files
│   ├── playbooks/            # Directory for playbook definitions
│   └── prompts/              # Custom agent prompts (optional overrides)
└── AGENTS.md                 # Agent context file (if not exists)
If you clone a repo with an existing .stoneforge/ directory but no database, sf init will create the database and auto-import from JSONL sync files.

​
Initialize Options

sf init [options]
OptionDescription
--name <name>Workspace name (optional)
--actor <actor>Default actor for operations
sf init

​
Configure Authentication

You do NOT configure API keys in Stoneforge. Authentication is configured within the underlying agent harness CLI (Claude Code, OpenCode, or Codex) and passes through automatically.

​
Provider Setup

Stoneforge supports three agent providers:
Install and authenticate with Claude Code:
npm install -g @anthropic-ai/claude-agent-sdk
claude-agent auth
Follow the authentication prompts. Your credentials are stored by Claude Code, not Stoneforge.
You can set the provider per-agent at registration with --provider opencode or per-session at start. The default provider is Claude Code.

​
Scaling with Multiple Plans

To split agents across multiple Claude MAX/Pro plans and avoid rate limits:
1

Install Claude Code with multiple accounts

Install Claude Code separately for each account, each with its own executable path.
2

Register agents with custom paths

Use the --executable flag when registering agents:
sf agent register worker-1 --role worker --executable /path/to/claude-account-1
sf agent register worker-2 --role worker --executable /path/to/claude-account-2
See the Smithy README for detailed multi-plan setup instructions.

​
Configuration File

The workspace configuration is stored in .stoneforge/config.yaml: 
# Default actor for CLI operations
actor: el-0000

# Merge provider: "github" or "local"
mergeProvider: local

# Test command for merge steward
testCommand: npm test

# Merge strategy: "squash" or "merge"
mergeStrategy: squash

# Auto-push after merge
autoPush: true

# Auto-cleanup worktrees after merge
autoCleanup: true
Edit config.yaml directly or use the dashboard settings page to modify configuration.

​
Verify Workspace Setup

Check that your workspace is properly initialized: 
sf stats
You should see workspace statistics including element counts, task status, and database information: 
Stoneforge Statistics

Elements:
  Task: 0
  Message: 0
  Document: 0
  Entity: 1
  ...

Tasks:
  Ready: 0
  Blocked: 0
  Closed: 0

Database:
  Path: .stoneforge/stoneforge.db
  Size: 32 KB

​
Shell Completion (Optional)

Enable shell completion for faster CLI usage:
Add to ~/.bashrc or ~/.bash_profile:
source <(sf completion bash)
Or save to a file:
sf completion bash > ~/.local/share/bash-completion/completions/sf

​
Development Installation

If you want to contribute to Stoneforge or use the latest development version:
# Clone the repository
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Link the CLI globally
cd packages/smithy
npm link
Development installations may have unstable features. Use published packages for production use.

​
Next Steps

Quick Start

Get orchestrating agents in under 5 minutes

Examples

See real-world usage patterns

​
Troubleshooting

The CLI executable may not have execute permissions. Fix with:
chmod +x $(which sf)
Or reinstall the package:
npm install -g @stoneforge/smithy
If sf init fails because .stoneforge/stoneforge.db exists, either:
  • Delete the existing database: rm .stoneforge/stoneforge.db
  • Or skip init if the workspace is already set up
If you have JSONL sync files, the database will be rebuilt from them on next sync.
Ensure your global npm bin directory is in your PATH:
echo $PATH | grep $(npm config get prefix)/bin
If missing, add to your shell profile:
export PATH="$(npm config get prefix)/bin:$PATH"

Build docs developers (and LLMs) love

Get started for freeTalk to us