Bonefish

A TypeScript framework for building and running multi-agent orchestrators. Define teams, pipelines, and workspaces in YAML. Bonefish executes them and enforces guardrails. Checkpointing and tracing modules are built but not yet wired into the runtime.

The virtual company (12 agents, thesis → prototype) is a template, not the product. Use it as-is, customize it, or build your own orchestrator from scratch.

Design informed by CrewAI, MetaGPT, AutoGen, ChatDev, and LangGraph.

Quick Start

npm install  # from the project root

# Scaffold a project with minimal starter config
bonefish init my-project --blank

# Validate configuration
bonefish validate -c my-project/config

# Dry run — prints the pipeline plan, spends zero tokens
bonefish run "AI-powered personal finance coaching for Gen Z in SEA" --dry-run -c my-project/config

Full pipeline execution is available via the programmatic API:

import { Orchestrator } from "bonefish";

const orch = new Orchestrator({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  dashscopeApiKey: process.env.BAILIAN_API_KEY,
  workspaceRoot: "./workspace",
  maxCostPerRun: 10, // required — no default
});

const result = await orch.run(
  "Thesis: AI-powered personal finance coaching for Gen Z in Southeast Asia"
);

Core Concepts

| Concept | Description | |---|---| | Agent | A role with a goal, backstory, model, provider, tools, and skills. Defined in agents.yaml. | | Pipeline | A sequence of phases, each containing steps and optional gates. Defined in pipeline.yaml. | | Step | A unit of work. Types: agent (LLM tokens), deterministic (zero tokens), loop (iterate over items). | | Gate | A decision point between phases. An agent evaluates metrics and issues a verdict: go, pivot, kill, or reject. | | Cycle | A review-fix loop within a step. Reviewer rejects → fixer revises → re-review. Max N cycles. | | Template | A pre-built orchestrator: agents + pipeline + actions + metrics + scaffold. | | Workspace | Where artifacts are stored. Pluggable: local filesystem (default), git (v2), custom. |

Built-in Templates

virtual-company

12 agents, 3 phases (research → execution → retro). Takes a thesis, researches it, writes a business plan, builds a prototype, reviews and tests it. Includes citation discipline, critique cycles, and CEO gates.

research-team

Lightweight research orchestrator: researcher + analyst + writer. 2 phases (research → synthesize). Planned for v1 — not yet available.

Configuration

Three files define an orchestrator:

| File | Purpose | |---|---| | bonefish.yaml | Project config: providers, guardrails, workspace type, tracing | | config/agents.yaml | Agent definitions: role, goal, backstory, model, provider, tools, skills, shell constraints | | config/pipeline.yaml | Phases, steps, gates, cycles, loops |

See manual.md for the full configuration reference.

Architecture

┌─────────────────────────────────────────────────┐
│  CLI: bonefish init | run | validate            │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Orchestrator Runtime                           │
│  Pipeline Runner │ Gates │ Guardrails │ Cycles  │
│  State Store │ Checkpoint Manager │ Tracing     │
│  Action Registry │ Metric Registry              │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Agent Layer                                    │
│  Team Builder │ Agent Loop │ Delegation         │
│  Persona Builder │ Skills Loader                │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Provider Layer                                 │
│  Anthropic │ OpenAI-Compatible │ Claude OAuth   │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Tool Layer                                     │
│  Shell (sandboxed) │ File R/W │ Web Fetch       │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Workspace Layer                                │
│  Local FS (default) │ Git (v2) │ Custom         │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Templates (composition root)                   │
│  Wire together the layers above.                │
│  src/ never imports from templates/.            │
│  Templates import from src/, not the reverse.   │
└─────────────────────────────────────────────────┘

Development

npm install
npm run build        # tsc
npm test             # vitest run
npm run typecheck    # tsc --noEmit across src, templates, and tests

v1 Limitations

These are honest constraints. They are on the roadmap for v2.

| Limitation | Detail | |---|---| | Phase-boundary checkpoints only | Steps within a phase are not individually resumable. No step-level state isolation. | | No MCP support | MCP tool integration is deferred to v2. | | Gate-boundary HITL only | Human gates fire at phase boundaries, not mid-step. Fails closed when humanGate: required and no callback is provided. | | Per-model pricing deferred | Cost estimation uses a flat rate. Per-model rate tables are planned. | | CLI run is dry-run only | bonefish run prints the plan but does not execute. Full execution uses the programmatic API. | | No OTLP export | Tracing writes JSON files. OpenTelemetry export is v2. |

License

MIT