zenflow

The multi-agent harness & workflow engine.

A production multi-agent harness. Declarative YAML agent workflows; an LLM coordinator routes events through hub-and-spoke mailboxes with race-safe delivery; agents call native MCP tools. One YAML file, one Go binary. Runs on any provider goai supports.

Website · Docs · Blueprint · Architecture · YAML Reference · Examples

---

See it run

A real zenflow flow spec/v1/examples/full-featured.yaml --model google/gemini-3-flash-preview --workdir /tmp/full-feature-gemini --yolo --plan run. The --plan flag prints the DAG before execution; the coordinator narrates every step boundary; four agents (planner, coder, reviewer, deployer) call read / write / glob / grep / bash tools to plan, implement, review, and ship a feature; the deploy_staging sub-workflow (loaded via includes:) runs after the main DAG completes. The cast that produced this recording is pinned at demos/full-featured.cast - replay it locally with asciinema play demos/full-featured.cast.

Core features

• Declarative YAML agent workflows. Multi-agent workflows expressed in a small composable spec: steps, dependencies, parallel fan-out, conditions (CEL), loops (forEach, repeat-until via untilAgent/maxIterations), includes for sub-workflow reuse, and tool steps (tool / toolInput) that invoke a registered goai tool directly without an LLM call.
• LLM coordinator with hub-and-spoke messaging. A coordinator agent narrates progress, forwards events between running steps, and finalizes the run. Peer agents never address each other directly.
• Race-safe Mailbox + Wake delivery. Every message is delivered through a per-agent mailbox with explicit drop reasons. No silent loss, no out-of-order delivery, no leaked goroutines.
• Native MCP tools. Point the harness at a Claude-compatible .zenflow/settings.json and every Model Context Protocol server's tools become available to your agents - stdio, HTTP, or SSE. No Go code, no recompile. Reference a whole server by name in an agent's tools:. See MCP servers.
• Multi-provider verified. Verified against Google gemini-3-pro-preview, AWS Bedrock (anthropic.claude-sonnet-4-6, minimax.minimax-m2.5), and Azure (DeepSeek-V3.2, claude-sonnet-4-6, gpt-5, gpt-5.3-codex) - any model goai supports works.
• Spec-first. Workflows validate against spec/v1/schema.json plus a Go validator with 40+ conformance fixtures BEFORE the first LLM call. Cycles, missing dependencies, unknown agents, malformed CEL - all rejected in milliseconds, not after a minute of model burn.
• Embed anywhere. CLI for one-shot runs (zenflow flow, zenflow goal, zenflow agent); Go library primitives (zenflow.New, Orchestrator.RunFlow) for embedding inside long-running services. Ships as a single static Go binary - no JVM, no Python interpreter, no Node runtime. go install, brew install, or curl | sh and you're running.

Install

The fastest path is the install script - it picks the right archive for your OS+arch from the latest GitHub Release, verifies the SHA-256 checksum, and drops zenflow into ~/.local/bin (or %LOCALAPPDATA%\Programs\zenflow on Windows).

# macOS / Linux
curl -fsSL https://zenflow.sh/install.sh | sh

# Windows (PowerShell)
iwr -useb https://zenflow.sh/install.ps1 | iex

Other options:

# Docker (linux/amd64 + linux/arm64 multi-arch image on GHCR)
docker pull ghcr.io/zendev-sh/zenflow:latest
docker run --rm \
  -e GEMINI_API_KEY \
  -e ZENFLOW_MODEL=google/gemini-2.0-flash \
  -v "$PWD":/wd -w /wd \
  ghcr.io/zendev-sh/zenflow:latest flow workflow.yaml

# Homebrew (macOS / Linux)
brew install zendev-sh/tap/zenflow

# Go install
go install github.com/zendev-sh/zenflow/cmd/zenflow@latest

# Manual download
# https://github.com/zendev-sh/zenflow/releases/latest

Requires Go 1.25+ when installing via go install or building from source. The Docker image runs as the distroless nonroot user and ships a static zenflow binary, no shell.

Quick start

Drop a workflow into a YAML file:

# debate.yaml
name: debate
agents:
  pro:    { description: "Argues IN FAVOR of the proposition." }
  con:    { description: "Argues AGAINST the proposition." }
  judge:  { description: "Impartial judge declaring a winner." }

steps:
  - id: team-pro
    agent: pro
    instructions: "Argue: 'AI assistants will replace junior dev roles within 5 years.'"

  - id: team-con
    agent: con
    instructions: "Argue against the same proposition."

  - id: verdict
    agent: judge
    instructions: "Declare a winner with reasoning."
    dependsOn: [team-pro, team-con]

Run it from the CLI:

export GEMINI_API_KEY=...
zenflow flow debate.yaml

For automated CI runs where you want to block shell access, add --sandbox:

zenflow flow debate.yaml --sandbox --model google/gemini-2.5-flash

--sandbox restricts tools to read, write, grep, and glob; bash is blocked even if --allow bash is also passed. See the CLI reference for the full permission flag set (--yolo, --allow, --deny, --strict).

Or embed in Go:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/zendev-sh/goai/provider/google"
    "github.com/zendev-sh/zenflow"
)

func main() {
    wf, err := zenflow.LoadWorkflow("debate.yaml")
    if err != nil {
        log.Fatal(err)
    }

    llm := google.Chat("gemini-2.0-flash", google.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
    orch := zenflow.New(
        zenflow.WithModel(llm),
        zenflow.WithCoordinator(zenflow.NewDefaultCoordRunner(llm)),
    )
    defer orch.Close()

    result, err := orch.RunFlow(context.Background(), wf)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Summary)
}

See examples/ for 19 runnable Go embeddings and spec/v1/examples/ for the matching YAML.

Three modes

zenflow exposes the same engine through three CLI verbs and one Go library surface:

Mode	What it does	Use when
zenflow flow workflow.yaml	Runs a fully-declared YAML DAG to completion.	The plan is fixed up-front; you want a deterministic execution.
zenflow goal "build a thing"	Asks the coordinator to plan and run a workflow on the fly.	The plan must adapt to user input or interim results.
zenflow agent "<prompt>"	Single-agent chat with optional tool loop.	One-shot agent calls; reuses zenflow's lifecycle hooks and provider routing.

The library form (zenflow.New(...).RunFlow(ctx, wf)) is the same engine; the CLI is a thin wrapper that resolves a provider from --model, wires the coordinator, and prints results.

MCP servers

Give agents tools from any Model Context Protocol server with a Claude-compatible .zenflow/settings.json - no Go code, no recompile:

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}" }
    }
  }
}

agents:
  crawler:
    description: "Crawls pages with firecrawl."
    tools: ["read", "write", "firecrawl"]   # bare server name = all its tools

zenflow flow crawl.yaml --model google/gemini-2.5-flash --verbose
# zenflow: MCP loaded 8 tool(s) from server(s) [firecrawl]

The CLI reads .zenflow/settings.json by default (override with --mcp-config, disable with --no-mcp); all three verbs use it. stdio, HTTP, and SSE transports are supported, with ${VAR} env expansion. Discovered tools are namespaced <server>__<tool>. Embedders get the same surface via LoadMCPConfig / ConnectMCPConfig / WithAdditionalTools. Full guide: MCP servers.

Documentation

Section	What's there
Getting Started	Install, first workflow, three-mode walkthrough.
Architecture	DAG executor, coordinator, Router, Mailbox, delivery engine (internal), lifecycle.
Concepts	Agents, scheduling, coordinator, messaging, failure handling, isolation, shared memory, observability, loops, conditions, composition, structured output, tools.
YAML Reference	Workflow / agent / step / loop schemas + CEL expression reference.
CLI Reference	Commands, flags, output formats.
Integrations	MCP servers, CI/CD, Docker, scripting, observability (OTel / Langfuse / Jaeger / Datadog).
Go API	Core functions, options (49 With* constructors), types, errors.
Examples	19 worked examples covering every primitive.
SKILL.md	Top-of-funnel context for AI agents that consume zenflow (tool description, env vars, YAML shape, NDJSON event schema, exit codes, decision flow). Follows the AI-skill format convention; reusable by any agent harness.

Compared to other multi-agent frameworks

zenflow takes a narrower position than CrewAI, AutoGen, and LangGraph: workflows are declarative YAML rather than Python control flow; messaging is mediated by a single coordinator instead of peer-to-peer; delivery is race-safe by construction via a mailbox + wake registry. See Compare for a side-by-side covering the tradeoffs each design makes.

Contributing

See CONTRIBUTING.md for dev setup, build/test commands, and the PR process.

AI contributors: two files cover different audiences and should not be confused.

• AGENTS.md (regenerated from CLAUDE.md by scripts/sync-agents-md.sh; pre-commit hook keeps them in sync) - instructions for AI agents editing the codebase. Code style, package layout, key rules, testing levels.
• SKILL.md - context for AI agents consuming zenflow as a tool. CLI verbs, env vars, YAML shape, NDJSON event schema, exit codes.

Community

• Code of Conduct - the standards we expect from all contributors and how to report violations.
• Security Policy - private vulnerability disclosure process; do not open a public issue for security reports.

License

Apache 2.0.