Stoneforge

https://github.com/stoneforge-ai/stoneforge
Admin
Stoneforge is a web dashboard and runtime for orchestrating AI coding agents, enabling parallel...
Tokens:219,001
Snippets:2,727
Trust Score:4.3
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Development Setup

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/CONTRIBUTING.md

Clone the repository, install dependencies, and run initial type checking.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install
npx turbo run typecheck
```

--------------------------------

### Provider Setup for OpenCode

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

Install the OpenCode SDK and verify its installation before registering agents with the `opencode` provider.

```bash
# Install OpenCode
npm install -g @opencode-ai/sdk

# Verify it's working
opencode --version

# Register agents with OpenCode provider
sf agent register e-worker-2 --role worker --provider opencode
```

--------------------------------

### Install and Initialize Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/introducing-stoneforge.mdx

Install the Stoneforge CLI globally, navigate to your project directory, and initialize a new Stoneforge project. Then, start the development server.

```bash
npm install -g @stoneforge/smithy
cd your-project
sf init
sf serve
```

--------------------------------

### Install and Initialize Stoneforge CLI

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Install the Stoneforge CLI globally using npm or pnpm. Then, initialize a workspace in your project directory and start the server.

```bash
# Install via npm or pnpm
npm install -g @stoneforge/smithy
# or
pnpm add -g @stoneforge/smithy

# Initialize workspace in your project (creates .stoneforge/ directory)
cd your-project
sf init

# Start the server and web dashboard at http://localhost:3457
sf serve

# Check system health
sf doctor
# Output:
# [OK] workspace: Workspace found at /Users/you/my-project/.stoneforge
# [OK] database: Database connection successful
# [OK] schema_version: Schema is at version 9 (up to date)
# Summary: 9 ok, 0 warnings, 0 errors
```

--------------------------------

### Install, Initialize, and Serve Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/free-open-source-ai-coding.mdx

Use these bash commands to install the Stoneforge CLI globally, initialize it in your project directory, and start the orchestration server. Ensure you have Node.js and npm installed.

```bash
# Install globally
npm install -g @stoneforge/smithy

# Initialize in your project
cd your-project
sf init

# Start the orchestration server
sf serve
```

--------------------------------

### Stoneforge CLI Installation and Initialization

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Instructions for installing the Stoneforge CLI globally and initializing a workspace in a git repository. Also includes commands to start the server and check system health.

```APIDOC
## Installation

Install the Stoneforge CLI globally and initialize a workspace in any git repository.

```bash
# Install via npm or pnpm
npm install -g @stoneforge/smithy
# or
pnpm add -g @stoneforge/smithy

# Initialize workspace in your project (creates .stoneforge/ directory)
cd your-project
sf init

# Start the server and web dashboard at http://localhost:3457
sf serve

# Check system health
sf doctor
```

### Output Example for `sf doctor`
```
[OK] workspace: Workspace found at /Users/you/my-project/.stoneforge
[OK] database: Database connection successful
[OK] schema_version: Schema is at version 9 (up to date)
Summary: 9 ok, 0 warnings, 0 errors
```
```

--------------------------------

### Quick Start: Create and Initialize Storage

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

Create a storage instance, which auto-detects the runtime, and then initialize the database schema. This example demonstrates synchronous operations.

```typescript
import { createStorage, initializeSchema } from '@stoneforge/storage';

// Auto-detects runtime (Bun, Node, or browser)
const storage = createStorage({ path: './data.db' });

// Run migrations to set up tables
initializeSchema(storage);

// Query rows
const tasks = storage.query('SELECT * FROM elements WHERE type = ?', ['task']);

// Insert a row
const result = storage.run(
  'INSERT INTO elements (id, type, data, created_at, updated_at, created_by) VALUES (?, ?, ?, ?, ?, ?)',
  ['el-1', 'task', '{}', new Date().toISOString(), new Date().toISOString(), 'system']
);
console.log(result.changes); // 1
```

--------------------------------

### Create a Deployment Playbook Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Example of creating a playbook named 'deploy' with specific steps and variables.

```bash
# Create a deployment playbook
sf playbook create -n deploy -t "Deployment Process" \
  -s "build:Build app" \
  -s "test:Run tests:build" \
  --variable "env:string" \
  --variable "debug:boolean:false:false"
```

--------------------------------

### External Sync Configuration Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples demonstrating how to set tokens, projects, and auto-link settings for GitHub and Linear.

```bash
sf external-sync config set-token github ghp_xxxxxxxxxxxx
```

```bash
sf external-sync config set-token linear lin_api_xxxxxxxxxxxx
```

```bash
sf external-sync config set-project github org/repo
```

```bash
sf external-sync config set-auto-link github
```

```bash
sf external-sync config disable-auto-link --type document
```

--------------------------------

### Install @stoneforge/core

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/core/README.md

Install the core package using npm.

```bash
npm install @stoneforge/core
```

--------------------------------

### Install @stoneforge/storage

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

Install the core package using npm.

```bash
npm install @stoneforge/storage
```

--------------------------------

### Install and Initialize Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/run-multiple-ai-coding-agents-parallel.mdx

Commands to clone the Stoneforge repository, install dependencies, link it globally, and then initialize it within your project.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
bun install
bun link

```

```bash
cd your-project
sf init

```

--------------------------------

### Install and Initialize Stoneforge

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/integrations/opencode.mdx

Install the Stoneforge CLI globally and then initialize it within your project directory. This prepares your project for Stoneforge orchestration.

```bash
# Install Stoneforge
npm install -g @stoneforge/cli

# Initialize in your project
sf init

# Configure for OpenCode in .stoneforge/config.yaml
# Start orchestrating
sf serve
```

--------------------------------

### Install Stoneforge CLI from source

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Clone the Stoneforge repository, install dependencies, build the project, and link the CLI globally.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install && pnpm build
pnpm link --global --filter @stoneforge/quarry
```

--------------------------------

### Install @stoneforge/ui Package

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/ui/README.md

Install the core UI package using npm. Ensure peer dependencies are also installed.

```bash
npm install @stoneforge/ui
```

```bash
npm install react react-dom @tanstack/react-query @tanstack/react-router
```

--------------------------------

### Provider Setup for Codex

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

Register agents with the `codex` provider. Ensure the `codex` CLI tool is installed separately.

```bash
# Register agents with Codex provider
sf agent register e-worker-3 --role worker --provider codex
```

--------------------------------

### Install Optional Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

For additional providers like OpenCode, install the corresponding optional dependency.

```bash
# OpenCode provider
npm install @opencode-ai/sdk
```

--------------------------------

### Install and Serve Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/tools/seo/output/directory-submissions.md

Install the Stoneforge CLI globally using npm and then initialize and serve the application. Access the running instance at http://localhost:3457.

```bash
npm install -g @stoneforge/smithy
sf init
sf serve
```

--------------------------------

### Install @stoneforge/smithy

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

Install the main package using npm. The default Claude provider is included.

```bash
npm install @stoneforge/smithy
```

--------------------------------

### Start the Daemon

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/auto-dispatch.mdx

Use this command to start the Stoneforge daemon process.

```bash
sf daemon start
```

--------------------------------

### Install Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Installs the Stoneforge command-line interface globally. Ensure Node.js 18+ or Bun is installed.

```bash
npm install -g @stoneforge/smithy
```

--------------------------------

### Install Stoneforge and Initialize for Codex

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/integrations/codex.mdx

Install the Stoneforge CLI globally and initialize a new project. After initialization, update the `.stoneforge/config.yaml` file to specify the 'codex' provider for your agents.

```bash
# Install Stoneforge
npm install -g @stoneforge/cli

# Initialize and configure for Codex
sf init

# Update .stoneforge/config.yaml to use codex provider
# Start orchestrating
sf serve
```

--------------------------------

### Provider Setup for Claude Code

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

If the `claude` CLI is already set up, you can register agents for Claude Code without needing to specify the provider. Verify the CLI installation first.

```bash
# Verify Claude Code is working
claude --version

# Register agents (claude-code is the default, no --provider needed)
sf agent register director --role director
sf agent register e-worker-1 --role worker
```

--------------------------------

### Install Stoneforge CLI with npm

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Use npm to install the Stoneforge CLI globally on your system.

```bash
npm install -g @stoneforge/quarry
```

--------------------------------

### sf install skills

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs Claude skills files to the `.claude/skills/` directory.

```APIDOC
## `sf install skills`

### Description
Installs Claude skills files to `.claude/skills/`. Use `--force` to overwrite existing files.

### Usage
```bash
sf install skills [--force]
```

### Parameters
#### Query Parameters
- **force** (boolean) - Optional - Overwrites existing files if true.
```

--------------------------------

### Install @stoneforge/quarry

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/quarry/README.md

Install the core SDK using npm. This command adds the package to your project's dependencies.

```bash
npm install @stoneforge/quarry
```

--------------------------------

### Clone and Install Stoneforge Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Instructions for cloning the Stoneforge repository and installing development dependencies using pnpm.

```bash
# Clone the repository
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge

# Install dependencies (uses pnpm)
pnpm install
```

--------------------------------

### Install Node.js/Browser Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

For Node.js or browser environments, install the corresponding optional dependencies.

```bash
# Node.js
npm install better-sqlite3

# Browser
npm install sql.js
```

--------------------------------

### Observe Daemon and Worker Activity

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/run-multiple-ai-coding-agents-parallel.mdx

Example logs showing the daemon dispatching tasks to workers and workers starting in their respective worktrees.

```text
[daemon] Dispatching "Refactor auth module" → e-worker-1
[daemon] Dispatching "Fix integration tests" → e-worker-2
[daemon] Dispatching "Add /api/v2/users endpoint" → worker-3

[e-worker-1] Starting in worktree: .stoneforge/.worktrees/e-worker-1-auth/
[e-worker-2] Starting in worktree: .stoneforge/.worktrees/e-worker-2-tests/
[worker-3] Starting in worktree: .stoneforge/.worktrees/worker-3-users/
```

--------------------------------

### Push Linked Elements Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples of pushing a single element, all elements, and all tasks with force.

```bash
sf external-sync push el-abc123
```

```bash
sf external-sync push --all
```

```bash
sf external-sync push --all --force --type task
```

--------------------------------

### Get top-level help

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Display general help information for the Stoneforge CLI.

```bash
sf --help
```

--------------------------------

### Register and Start a Director Agent

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

Use these commands to register a new director agent and then start it. The director runs as a persistent session.

```bash
sf agent register director --role director
sf agent start <id>
```

--------------------------------

### Runtime Detail Configuration Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Illustrates the configuration details displayed for a runtime, including mode, host, mode-specific settings, and timestamps.

```text
- Mode: Worktree / Docker
- Host: {host name} — {os} {arch}
- Worktree Path or Docker Image (mode-specific)
- Created: timestamp
- Last Health Check: timestamp
```

--------------------------------

### Install @stoneforge/shared-routes

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/shared-routes/README.md

Install the package using npm. Hono is included as a dependency.

```bash
npm install @stoneforge/shared-routes
```

--------------------------------

### Start Stoneforge Server and Dashboard

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Starts the Stoneforge server and makes the web dashboard accessible at http://localhost:3457.

```bash
sf serve
```

--------------------------------

### Clone and Initialize Stoneforge Repository

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Steps to clone the Stoneforge repository, install dependencies, and initialize the workspace.

```bash
# Clone the repo
git clone https://github.com/stoneforge-ai/stoneforge
cd stoneforge

# Init Stoneforge (make sure you've globally installed stoneforge NPM package)
pnpm install && sf init

# Start stoneforge server
sf serve
```

--------------------------------

### Start Development Server

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Start the development server for the Stoneforge project. Use 'pnpm dev:smithy' for orchestrator services only, or 'pnpm dev' for all services.

```bash
# Orchestrator only (smithy-server + smithy-web)
pnpm dev:smithy

# Everything (all 4 services)
pnpm dev
```

--------------------------------

### Verify CLI installation

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Check if the Stoneforge CLI is installed correctly by displaying its version.

```bash
sf --version
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Install all necessary project dependencies using pnpm, the monorepo package manager.

```bash
pnpm install
```

--------------------------------

### CLI: Start and Manage Agents

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Start, list, and stop agents using the 'sf agent' command. Agents can be started with custom prompts and model overrides. List agents with various filters.

```bash
# Start the Director (use ID from register output)
sf agent start <director-id>

# Start with a custom prompt and model override
sf agent start <id> --prompt "Focus on the authentication module" --model claude-opus-4

# List agents (with filters)
sf agent list
sf agent list --role worker --status idle
sf agent list --workerMode ephemeral --hasSession

# Stop an agent
sf agent stop <id>
sf agent stop <id> --no-graceful --reason "Rate limit hit"

# Stream live agent output
sf agent stream <id>

```

--------------------------------

### Initialize Stoneforge Project

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/_template.mdx

Use this command to initialize a new Stoneforge project. Ensure the Stoneforge CLI is installed and accessible in your PATH.

```bash
stoneforge init
```

--------------------------------

### Install Skills

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs Claude skills files to the `.claude/skills/` directory. Use `--force` to overwrite existing files.

```bash
sf install skills [--force]
```

--------------------------------

### Quick Start: Initialize and Register Agents

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

Initialize storage and the schema, create the OrchestratorAPI, and register a director and an ephemeral worker.

```typescript
import { createOrchestratorAPI } from '@stoneforge/smithy';
import { createStorage, initializeSchema } from '@stoneforge/storage';

// Create a storage backend and initialize the schema
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

// Create the OrchestratorAPI (extends QuarryAPI)
const api = createOrchestratorAPI(storage);

// Register a director agent
const director = await api.registerDirector({
  name: 'lead',
  createdBy: humanEntityId,
});

// Register an ephemeral worker
const worker = await api.registerWorker({
  name: 'dev-1',
  workerMode: 'ephemeral',
  createdBy: director.id,
  reportsTo: director.id,
});

// Assign a task to the worker (auto-generates branch and worktree names)
await api.assignTaskToAgent(taskId, worker.id);
```

--------------------------------

### Runtime List Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Displays a flat list of runtimes with inline host information, including name, mode, host, status, and agent count.

```text
staging-worktree    Worktree   staging-1    ● Online    0 agents
my-macbook          Worktree   adam-macbook ● Online    3 agents   default
docker-sandbox      Docker     adam-macbook ● Online    1 agent
gpu-docker          Docker     gpu-rack-3   ○ Offline   2 agents
```

--------------------------------

### Install Stoneforge from Source

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Clone the Stoneforge repository, install dependencies, and build the project from source. This method is useful for developers contributing to Stoneforge or needing the latest unreleased changes.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
pnpm install
pnpm build
```

--------------------------------

### sf agent start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Starts a registered agent, optionally with an initial prompt or specific session parameters.

```APIDOC
## sf agent start

### Description
Starts a registered agent, allowing for an initial prompt, specific spawn mode, and environment variables.

### Method
CLI Command

### Endpoint
sf agent start <id> [options]

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to start.

#### Query Parameters
- **-p, --prompt** (string) - Optional - Initial prompt to send to agent.
- **-m, --mode** (string) - Optional - Spawn mode: `headless`, `interactive`.
- **-r, --resume** (string) - Optional - Provider session ID to resume.
- **-w, --workdir** (string) - Optional - Working directory for agent.
- **--cols** (integer) - Optional - Terminal columns for interactive mode (default: 120).
- **--rows** (integer) - Optional - Terminal rows for interactive mode (default: 30).
- **--timeout** (integer) - Optional - Timeout in milliseconds (default: 120000).
- **-e, --env** (string) - Optional - Environment variable (repeatable, format: `KEY=VALUE`).
- **-t, --taskId** (string) - Optional - Task ID to assign to agent.
- **--stream** (boolean) - Optional - Stream agent output after starting.
- **--provider** (string) - Optional - Override agent provider for this session.
- **--model** (string) - Optional - Override model for this session.
```

--------------------------------

### Install OpenCode Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Install the OpenCode agent provider CLI globally using npm. This is an alternative provider for Stoneforge.

```bash
npm install -g @opencode-ai/sdk
```

--------------------------------

### Start Stoneforge Server

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Starts the Stoneforge server and web dashboard. You can specify the component to serve (orchestrator or data platform) and the port.

```bash
# Start the orchestrator server + dashboard
sf serve
# or explicitly:
sf serve smithy --port 3457
```

```bash
# Start just the Quarry data server
sf serve quarry --port 3456
```

--------------------------------

### Install Stoneforge Packages

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Instructions for installing Stoneforge packages in your project using npm, including core, storage, and quarry.

```bash
npm install @stoneforge/core @stoneforge/storage @stoneforge/quarry

# Or install individual packages as needed
npm install @stoneforge/smithy    # Agent orchestration
npm install @stoneforge/ui        # React component library
```

--------------------------------

### Start Stoneforge Development Services

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Commands to start different components of the Stoneforge development environment, including the orchestrator and the full stack.

```bash
# Start the orchestrator (most common)
pnpm dev:smithy

# Start everything (all 4 services)
pnpm dev

# Start just the data platform (quarry only)
pnpm dev:platform
```

--------------------------------

### Link External Item Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples of linking a task to a GitHub issue and a document to a Linear item.

```bash
sf external-sync link el-abc123 https://github.com/org/repo/issues/42
```

```bash
sf external-sync link el-doc456 https://linear.app/team/DOC-1 --provider linear --type document
```

--------------------------------

### Start the Director Agent

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Starts the previously registered Director agent. Use the ID provided by the registration command.

```bash
sf agent start <id>
```

--------------------------------

### Start an Agent Session

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Start an agent session with options for initial prompt, spawn mode, resuming a session, working directory, terminal size, timeout, environment variables, task assignment, streaming output, and overriding provider or model.

```bash
sf agent start <id> [options]
```

--------------------------------

### Create a Feature Plan with Tasks

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Demonstrates creating a plan and then adding multiple tasks with priorities. This example outlines a typical feature decomposition workflow.

```bash
sf plan create --title "Shopping Cart"
sf task create --title "Cart data model and API" --priority 1 --plan "Shopping Cart"
sf task create --title "Add-to-cart UI" --priority 2 --plan "Shopping Cart"
sf task create --title "Cart summary sidebar" --priority 2 --plan "Shopping Cart"
sf task create --title "Checkout flow" --priority 2 --plan "Shopping Cart"
sf task create --title "Integration tests" --priority 3 --plan "Shopping Cart"
```

--------------------------------

### Daemon Section Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Shows the Dispatch Daemon status and uptime at the top of the runtime list, with an option to change the host.

```text
Dispatch Daemon  ● Running  Up 30 min ago
Host: staging-1  [Change host]
```

--------------------------------

### Example of using --json flag

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Demonstrates how to use the `--json` flag for machine-readable output, often piped to tools like `jq`.

```bash
sf create task --title "Fix bug" --json
```

--------------------------------

### Bulk Link External Items Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Examples of bulk linking using GitHub, with and without a dry run, and linking documents from a specific provider.

```bash
sf external-sync link-all --provider github --dry-run
```

```bash
sf external-sync link-all --provider github --status open --status in_progress
```

```bash
sf external-sync link-all --provider folder --type document
```

--------------------------------

### Dependencies JSONL Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/storage.mdx

An example of the JSONL format for the 'dependencies' file, illustrating how dependency relationships are represented as individual JSON objects on separate lines.

```jsonl
{"blockedId":"el-3a8f","blockerId":"el-7b2c","type":"blocks","createdAt":"...","createdBy":"director-1","metadata":{}}
```

--------------------------------

### Plan Creation and Task Management Workflow

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

This example demonstrates a recommended workflow for managing plans and tasks: creating a plan, adding tasks, setting dependencies, and activating the plan.

```bash
# Recommended workflow
sf plan create --title "Feature X"                        # 1. Create (draft)
sf create task --title "Task 1" --plan "Feature X"        # 2. Add tasks
sf dependency add --type=blocks el-task2 el-task1          # 3. Set deps
sf plan activate <plan-id>                                 # 4. Activate
```

--------------------------------

### Daemon Runtime Detail Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/smithy-next/specs/unified-runtime-architecture.md

Shows the additional 'Dispatch Daemon' info section that appears when viewing the daemon host's runtime, including status and uptime.

```text
When viewing the daemon host's runtime, a "Dispatch Daemon" info section appears showing daemon status and uptime.
```

--------------------------------

### Dependency Gate Metadata Examples

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/core-types.mdx

Provides examples of metadata structures for the 'awaits' dependency type, including timer, approval, external, and webhook gates.

```typescript
// Timer gate
{ gateType: 'timer', waitUntil: Timestamp }

// Approval gate
{ gateType: 'approval', requiredApprovers: EntityId[], currentApprovers?: EntityId[] }

// External gate
{ gateType: 'external', externalSystem: string, externalId: string, satisfied?: boolean }

// Webhook gate
{ gateType: 'webhook', webhookUrl?: string, callbackId?: string, satisfied?: boolean }
```

--------------------------------

### Quick Start: Async Initialization for Browser

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/storage/README.md

Use `createStorageAsync` for browser environments where WASM loading is asynchronous. The API remains synchronous after initialization.

```typescript
import { createStorageAsync, initializeSchema } from '@stoneforge/storage';

// Async factory required for browser (WASM loading)
const storage = await createStorageAsync({ path: 'stoneforge.db' });
initializeSchema(storage);
```

--------------------------------

### Customize Documentation Standards in Workspace Prompts

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/documentation-generation.mdx

Define documentation standards and guidelines within your workspace prompts to ensure consistency in tone, structure, and content. This example shows how to set expectations for active voice, code examples, and error case documentation.

```bash
# Customize documentation standards in workspace prompts
# .stoneforge/prompts/worker.md:
# "Write docs in active voice. Include a code example for every
#  public function. Document error cases, not just happy paths.
#  Use the existing docs/ structure and link between related pages."
```

--------------------------------

### Install Stoneforge CLI with pnpm

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Install the Stoneforge CLI globally using pnpm. This command is for users who prefer pnpm as their package manager.

```bash
pnpm add -g @stoneforge/smithy
```

--------------------------------

### Ephemeral Worker Worktree and Branch Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/worktree-isolation.mdx

Illustrates the directory path for an ephemeral worker's worktree and its corresponding git branch name. This setup ensures each task has a unique, isolated environment.

```shell
Worktree: .stoneforge/.worktrees/e-worker-1-implement-login/
Branch:   agent/e-worker-1/el-3a8f-implement-login
```

--------------------------------

### Start Stoneforge data platform

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Run only the Stoneforge data platform (Quarry) on a specified port.

```bash
sf serve quarry --port 3456
```

--------------------------------

### Stoneforge Development Workflow: Build and Test

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/AGENTS.md

Commands for installing dependencies, building all packages, and running the test suite. Includes a watch mode for continuous testing during development.

```bash
bun install           # Install dependencies
```

```bash
bun run build         # Build all packages
```

```bash
bun test              # Run test suite
```

```bash
bun test --watch      # Watch mode
```

--------------------------------

### Initialize Documentation Library

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Bootstraps the Documentation library and directory for a workspace. This operation is idempotent.

```bash
sf docs init [--json] [--quiet]
```

--------------------------------

### Handoff Notes Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/worktree-isolation.mdx

An example of a handoff note appended to a task's description document, providing context for the next worker about attempted actions and encountered issues.

```text
[AGENT HANDOFF NOTE]: Completed API integration and unit tests.
Unable to resolve CORS issue — requires infrastructure access.
Branch contains working local implementation with all endpoints.
```

--------------------------------

### Example Plan Structure

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Illustrates the hierarchical structure of a plan with tasks, their priorities, and dependencies.

```text
Plan: "User Authentication"  [status: active]
│
├── Task 1: Set up auth middleware         [priority: 1]
├── Task 2: Create login endpoint          [priority: 2, blocked by 1]
├── Task 3: Create signup endpoint         [priority: 2, blocked by 1]
├── Task 4: Build login form component     [priority: 2]
├── Task 5: Build signup form component    [priority: 2]
├── Task 6: Write auth middleware tests    [priority: 3, blocked by 1]
├── Task 7: Write endpoint integration tests [priority: 3, blocked by 2, 3]
└── Task 8: Write component tests          [priority: 3, blocked by 4, 5]
```

--------------------------------

### Elements JSONL Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/storage.mdx

An example of the JSONL format for the 'elements' file, showing individual JSON objects per line, each containing all necessary data to reconstruct an element.

```jsonl
{"id":"el-3a8f","type":"task","title":"Fix login bug","status":"open","createdAt":"...","createdBy":"director-1","tags":[],"metadata":{}}
{"id":"el-7b2c","type":"task","title":"Add tests","status":"closed","createdAt":"...","createdBy":"director-1","tags":["testing"],"metadata":{}}
```

--------------------------------

### sf embeddings install

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-core.mdx

Installs a local model for embeddings.

```APIDOC
## `sf embeddings install`

### Description
Installs a local model for embeddings.

### Usage
```bash
sf embeddings install
```
```

--------------------------------

### Clone Stoneforge Repository

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Clone the Stoneforge repository and navigate into the project directory to begin development setup.

```bash
git clone https://github.com/stoneforge-ai/stoneforge.git
cd stoneforge
```

--------------------------------

### Get subcommand help

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Show help details for a specific subcommand, such as 'task'.

```bash
sf task --help
```

--------------------------------

### Initialize and Wire Up Services

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/orchestrator-services.mdx

Demonstrates the creation and integration of various services like dependency, cache, priority, and inbox services, including wiring up status transition callbacks.

```typescript
import {
  createDependencyService,
  createBlockedCacheService,
  createPriorityService,
  createInboxService,
  createIdLengthCache,
} from '@stoneforge/quarry';

const depService = createDependencyService(storage);
const blockedCache = createBlockedCacheService(storage);
const priorityService = createPriorityService(storage);
const inboxService = createInboxService(storage);
const idLengthCache = createIdLengthCache(storage);

// Wire up auto-transitions
blockedCache.setStatusTransitionCallback({
  onBlock: (elementId, previousStatus) => {
    storage.run(
      'UPDATE elements SET data = json_set(data, "$.status", ?) WHERE id = ?',
      ['blocked', elementId],
    );
  },
  onUnblock: (elementId, statusToRestore) => {
    storage.run(
      'UPDATE elements SET data = json_set(data, "$.status", ?) WHERE id = ?',
      [statusToRestore, elementId],
    );
  },
});
```

--------------------------------

### Quick Start with IDs and Errors

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/core/README.md

Demonstrates generating and parsing IDs, and throwing structured errors using factory functions. Ensure necessary imports are included.

```typescript
import { generateId, generateChildId, parseId } from '@stoneforge/core/id';
import type { Task, Entity } from '@stoneforge/core/types';
import { notFound, invalidInput } from '@stoneforge/core/errors';

// Generate a root ID
const taskId = await generateId({ identifier: 'implement-auth', createdBy: 'el-abc' });

// Generate a child ID scoped to a parent
const subtaskId = generateChildId(taskId, 1);

// Parse an ID back into its components
const { hash, depth, isRoot } = parseId(subtaskId);

// Throw structured errors with factory functions
throw notFound('task', taskId);
throw invalidInput('title', 'Title is required');
```

--------------------------------

### Initialize Storage and Quarry API

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/quarry/README.md

Set up the storage backend and initialize the Quarry API. This involves creating a storage instance and then passing it to `createQuarryAPI`.

```typescript
import { createStorage, initializeSchema } from '@stoneforge/storage';
import { createQuarryAPI } from '@stoneforge/quarry/api';
import type { Task } from '@stoneforge/core';

// Create a StorageBackend (auto-detects Bun/Node runtime)
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

// Create the API
const api = createQuarryAPI(storage);
```

--------------------------------

### Dependency Graph Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/dependency-system.mdx

Illustrates a basic blocking dependency relationship between two elements in the dependency graph.

```text
blockedId ──────── type ────────▶ blockerId

"el-3a8f"  ─── blocks ──────────▶ "el-7b2c"
(waiting)                          (must complete first)
```

--------------------------------

### Quick Start with @stoneforge/ui Components and Hooks

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/ui/README.md

Demonstrates basic usage of @stoneforge/ui components like Card and Button, along with hooks for theme management (useTheme) and WebSocket communication (useWebSocket).

```tsx
import '@stoneforge/ui/styles/tokens.css';
import { Button, Card, CardHeader, CardTitle, CardContent } from '@stoneforge/ui';
import { useTheme, useWebSocket } from '@stoneforge/ui/hooks';

function App() {
  const { isDark, toggleDarkMode } = useTheme();
  const { connectionState } = useWebSocket({
    url: 'ws://localhost:3456/ws',
    channels: ['tasks'],
  });

  return (
    <Card>
      <CardHeader>
        <CardTitle>Dashboard</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Connection: {connectionState}</p>
        <Button variant="primary" onClick={toggleDarkMode}>
          {isDark ? 'Light Mode' : 'Dark Mode'}
        </Button>
      </CardContent>
    </Card>
  );
}
```

--------------------------------

### Get specific command help

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Display help for a particular command, including its flags and arguments, like 'dep add'.

```bash
sf dep add --help
```

--------------------------------

### Create Documentation Directory

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/src/prompts/director.md

Use this command to create the initial Documentation Directory document. This serves as the central index for all workspace documentation.

```bash
sf document create --title "Documentation Directory" --type markdown --category reference \
  --metadata '{"purpose": "document-directory"}' \
  --content "# Documentation Directory\n\nIndex of all workspace documents.\n\n## Specs\n\n(none yet)\n\n## References\n\n(none yet)\n\n## Decision Log\n\n(none yet)"
```

--------------------------------

### sf daemon start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Starts the dispatch daemon, which automatically assigns tasks to idle workers.

```APIDOC
## sf daemon start

### Description
Starts the dispatch daemon, responsible for auto-assigning tasks to idle workers. This command is typically only needed if running the daemon separately from `sf serve`.

### Method
CLI Command

### Endpoint
sf daemon start [--server <url>]

### Parameters
#### Query Parameters
- **--server** (string) - Optional - The URL of the orchestrator server.
```

--------------------------------

### Initialize a Stoneforge workspace

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-overview.mdx

Run `sf init` in your project root to set up the necessary Stoneforge configuration files and directories.

```bash
sf init --name my-project
```

--------------------------------

### Create Documentation Plan with Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/documentation-generation.mdx

Use the Stoneforge CLI to create a plan for generating documentation. Specify the title, a detailed description of the desired output, and the target directory.

```bash
sf plan create --title "Generate API documentation" \
  --description "Generate API docs for all public endpoints. Include request/response examples, error codes, and authentication requirements. Output as MDX files in docs/api/."
```

--------------------------------

### Orphan Recovery Problem Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/orchestration-loop.mdx

Illustrates the state of task assignments before and after an orchestrator server restart, highlighting the orphan task problem.

```text
Before restart:
  e-worker-1 -> session running -> task "el-3a8f" in progress

After restart:
  e-worker-1 -> session idle -> task "el-3a8f" still assigned, status IN_PROGRESS
  (worker availability polling skips this worker — it already has an assigned task)
```

--------------------------------

### Initialize and Configure Stoneforge CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/claude-code-teams-vs-self-hosted.mdx

Set up a self-hosted AI coding agent environment using the Stoneforge CLI. Configure the AI provider and API key, then start the orchestration daemon.

```bash
sf init
sf config set provider anthropic
sf config set api-key $ANTHROPIC_API_KEY
sf daemon start --workers 3
```

--------------------------------

### QuarryAPI Initialization

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Code example for creating and configuring the core data API for programmatic access to all Stoneforge data using the Quarry SDK.

```APIDOC
## QuarryAPI — Initialization

Create and configure the core data API for programmatic access to all Stoneforge data.

```typescript
import { createQuarryAPI } from '@stoneforge/quarry';
import { createStorage, initializeSchema } from '@stoneforge/storage';

const storage = createStorage({ path: '.stoneforge/stoneforge.db' });
initializeSchema(storage);
const api = createQuarryAPI(storage);
```
```

--------------------------------

### Example Goal for Director

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

This is an example of a focused goal that can be sent to the Director agent for planning and task creation.

```plaintext
# Example goal
Add OAuth login with Google and GitHub providers.
Include error handling and rate limiting.
```

--------------------------------

### Override Model at Session Start

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/multi-provider.mdx

You can override the default or registered model for an agent on a one-time basis when starting a session.

```bash
sf agent start <id> --model claude-opus-4-6
```

--------------------------------

### Define Task Steps in a Playbook

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/workflows-and-playbooks.mdx

Example of defining two task steps in a playbook, showing sequential execution and dependency. Use this for standard agent tasks.

```yaml
steps:
  - id: setup_db
    title: "Set up {{env}} database schema"
    description: "Create tables and indexes for {{env}}"
    priority: 1

  - id: run_migrations
    title: "Run database migrations"
    dependsOn: [setup_db]
    priority: 2
```

--------------------------------

### Create a Playbook

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/workflows-and-playbooks.mdx

Use this command to create a new playbook with defined steps and dependencies. Specify steps with their IDs, titles, priorities, and optional dependencies.

```bash
sf playbook create nightly_cleanup \
  --title "Nightly Cleanup" \
  --step "gc_workflows:Garbage collect workflows:1" \
  --step "gc_worktrees:Clean stale worktrees:2:gc_workflows" \
  --step "health_check:Run agent health checks:3:gc_worktrees"
```

--------------------------------

### Worker Handoff Note Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

This is an example of a handoff note appended to a task description when a worker cannot complete it and needs to pass it on.

```plaintext
[AGENT HANDOFF NOTE]: Completed API integration. Unable to resolve
CORS issue — requires infrastructure access. Branch contains working
local implementation.
```

--------------------------------

### Initialize Stoneforge Workspace

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/quick-start.mdx

Initializes a new Stoneforge workspace in your project directory. Navigate to your project first.

```bash
cd your-project
sf init
```

--------------------------------

### Using Stoneforge Quarry API in TypeScript

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/README.md

Example demonstrating how to initialize the Quarry API, create tasks, query ready work, add dependencies, and search documents using FTS5.

```typescript
import { createQuarryAPI } from "@stoneforge/quarry";
import { createStorage, initializeSchema } from "@stoneforge/storage";

// Create API instance
const storage = createStorage(".stoneforge/stoneforge.db");
initializeSchema(storage);
const api = createQuarryAPI(storage);

// Create a task
const task = await api.create({
  type: "task",
  title: "Implement feature X",
  priority: 2,
  createdBy: entityId,
});

// Query ready work (unblocked, open tasks)
const ready = await api.ready();

// Add a dependency
await api.addDependency({
  blockerId: prerequisiteTask.id,
  blockedId: task.id,
  type: "blocks",
});

// Search documents with FTS5
const results = await api.searchDocumentsFTS("authentication flow", {
  hardCap: 10,
});
```

--------------------------------

### Initialize Stoneforge Project

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Run the Stoneforge initialization command within a git repository. This sets up the necessary configuration files and directories for your project.

```bash
sf init
```

--------------------------------

### Create Migration Plan

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/use-cases/framework-migrations.mdx

Use the `sf plan create` command to initiate a migration plan. The Director agent will then break this down into dependency-ordered tasks.

```bash
# Create a plan for the migration
sf plan create --title "Migrate from JavaScript to TypeScript"

# The Director breaks this into dependency-ordered tasks:
# Phase 1 (parallel): Add tsconfig.json, install dependencies
# Phase 2 (parallel): Migrate src/types/ and src/utils/ (no deps)
# Phase 3 (parallel): Migrate src/services/ (depends on types)
# Phase 4 (parallel): Migrate src/components/ (depends on utils)
# Phase 5 (parallel): Migrate src/pages/ (depends on components)
# Phase 6: Update build config and CI pipeline
```

--------------------------------

### Prompt Identity Section Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/custom-prompts.mdx

An example of the 'Identity' section of a prompt, defining the agent's role, responsibilities, and reporting structure.

```markdown
# Your Role: Worker

You are a worker agent in the Stoneforge orchestration system.

## Your Responsibilities
- Execute assigned tasks
- Report progress and blockers
- Request help when stuck

## Who You Report To
- Director agent
```

--------------------------------

### Install Claude Code Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Install the Claude Code agent provider CLI globally using npm. This is the default provider for Stoneforge.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Query Agents

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/smithy/README.md

Retrieve agent information using various query methods like get, get by name, list all, or filter by role.

```typescript
const agent = await api.getAgent(entityId);
const agentByName = await api.getAgentByName('Worker-1');
const allAgents = await api.listAgents();
const workers = await api.listAgents({ role: 'worker' });
const director = await api.getDirector();
const stewards = await api.getStewards();
const available = await api.getAvailableWorkers();
```

--------------------------------

### Create and Use Sync Service

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/packages/quarry/README.md

Initializes the storage and schema, then creates a sync service. Demonstrates exporting data to a JSONL directory and importing data from it.

```typescript
import { createSyncService } from '@stoneforge/quarry/sync';
import { createStorage, initializeSchema } from '@stoneforge/storage';

const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

const sync = createSyncService(storage);

// Export to JSONL directory
await sync.export({ outputDir: '.stoneforge/sync' });

// Import from JSONL directory
await sync.import({ inputDir: '.stoneforge/sync' });
```

--------------------------------

### Run Full Test Suite and Linting

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/community/contributing.mdx

Execute the full test suite, linting, and type checking for the entire project.

```bash
pnpm test
pnpm lint
pnpm typecheck
```

--------------------------------

### Get Event History for an Element

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Retrieve the event history for a specific element or list all 'created' events. An element ID is required to get its history.

```typescript
const events = await api.getEvents(elementId);
```

```typescript
const allCreated = await api.listEvents({ eventType: 'created' });
```

```typescript
const count = await api.countEvents({ elementId });
```

--------------------------------

### Create Playbook with CLI

Source: https://context7.com/stoneforge-ai/stoneforge/llms.txt

Define reusable process templates using the `sf playbook create` command. Specify steps with IDs, titles, priorities, and dependencies.

```bash
# CREATE a playbook with steps (id:title:priority[:dependsOn])
sf playbook create nightly_cleanup \
  --title "Nightly Cleanup" \
  --step "gc_workflows:Garbage collect workflows:1" \
  --step "gc_worktrees:Clean stale worktrees:2:gc_workflows" \
  --step "health_check:Run agent health checks:3:gc_worktrees"
```

--------------------------------

### Create a Plan as Immediately Active

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Create a plan and set its status to 'active' simultaneously. Use this cautiously for plans without dependencies where immediate dispatch is desired.

```bash
sf plan create --title "Hotfix" --status active
```

--------------------------------

### Start Dispatch Daemon

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-orchestration.mdx

Start the dispatch daemon, which automatically assigns tasks to idle workers. This command is typically only needed if running the daemon separately from `sf serve`.

```bash
sf daemon start [--server <url>]
```

--------------------------------

### JSONL Source of Truth Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/website/src/content/blog/introducing-stoneforge.mdx

This is an example of the JSONL format used by Stoneforge. Each line represents an immutable record of an element's state, suitable for version control.

```jsonl
{"type":"element","id":"el-abc123","elementType":"task","title":"Implement OAuth","status":"closed","priority":1,"assignee":"worker-1","createdBy":"director-1"}
{"type":"element","id":"el-def456","elementType":"task","title":"Build login UI","status":"in_progress","priority":2,"assignee":"worker-2","createdBy":"director-1"}
{"type":"element","id":"el-ghi789","elementType":"task","title":"Write integration tests","status":"open","priority":3,"createdBy":"director-1"}
```

--------------------------------

### Install OpenAI Codex Provider

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/getting-started/installation.mdx

Install the OpenAI Codex agent provider CLI globally using npm. This provider is used for interacting with OpenAI's Codex models.

```bash
npm install -g @openai/codex
```

--------------------------------

### Activate a Plan via CLI

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Once all tasks and dependencies are set up, activate the plan to make its tasks dispatchable by the daemon.

```bash
sf plan activate <plan-id>
```

--------------------------------

### Playbook Inheritance Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/workflows-and-playbooks.mdx

Example demonstrating playbook inheritance using the `extends` field. This allows composing playbooks by extending existing ones and overriding or adding variables and steps.

```yaml
name: deploy_with_tests
title: "Deploy with Test Suite"
extends: [base_deploy]

variables:
  - name: test_command
    type: string
    required: false
    default: "npm test"

steps:
  - id: run_tests
    title: "Run test suite"
    description: "Execute {{test_command}}"
    dependsOn: [setup_db]  # Reference parent step
```

--------------------------------

### Start an ephemeral worker on a specific task

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/agent-roles.mdx

Manually start an ephemeral worker on a specific task, bypassing the dispatch daemon. Useful for one-off work where precise control over agent assignment is needed.

```bash
sf agent start <agent-id> --taskId <task-id>
```

--------------------------------

### Task Assignment Dispatch Message Example

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/core-concepts/orchestration-loop.mdx

Example of a dispatch message sent to a worker's inbox, containing all necessary context for task execution, including worker ID, task details, priority, description, and acceptance criteria.

```markdown
## Task Assignment

Worker ID: e-worker-1
Director ID: director
Task ID: el-3a8f
Title: Add OAuth login
Priority: 1

### Description
{full description content, including any handoff notes from previous workers}

### Acceptance Criteria
{acceptance criteria if present}

### Instructions
1. Read the task title and acceptance criteria carefully.
2. Complete the task: make changes, commit, push, then run: sf task complete el-3a8f
```

--------------------------------

### Initialization

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/quarry-api.mdx

Initialize the Quarry API by creating a storage instance and then creating the API with the storage.

```APIDOC
## Initialization

```typescript
import { createQuarryAPI } from '@stoneforge/quarry';
import { createStorage, initializeSchema } from '@stoneforge/storage';

const storage = createStorage({ path: '.stoneforge/stoneforge.db' });
initializeSchema(storage);
const api = createQuarryAPI(storage);
```
```

--------------------------------

### Get Director

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/orchestrator-api.mdx

Retrieves the primary Director agent.

```APIDOC
## Get Director

### Description
Retrieves the primary Director agent.

### Method
`api.getDirector`

### Response Example
```typescript
const director = await api.getDirector();
```
```

--------------------------------

### Show Plan Details with Tasks

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/guides/task-planning.mdx

Display detailed information about a specific plan, including all associated tasks.

```bash
sf plan show <plan-id> --tasks
```

--------------------------------

### Get System Stats

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/quarry-api.mdx

Retrieves statistics about the Quarry system.

```APIDOC
## System Stats

### Description
Retrieves statistics about the Quarry system.

### Method
`api.stats()`

### Request Example
```typescript
const stats = await api.stats();
```
```

--------------------------------

### Create a channel

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/cli-data.mdx

Creates a new channel with specified name, description, type, visibility, policy, and members.

```bash
sf channel create --name <name> [--description <text>] [--type group|direct] [--visibility public|private] [--policy open|invite-only|request] [--member <id>] [--direct <entity>] [--tag <tag>]
```

--------------------------------

### Get Workflow Progress

Source: https://github.com/stoneforge-ai/stoneforge/blob/master/apps/docs/src/content/docs/reference/quarry-api.mdx

Retrieve the progress status of a workflow.

```typescript
const progress = await api.getWorkflowProgress(workflowId);
```
Tokens:
Raw