zenflow

name	zenflow
description	Multi-agent workflow engine for Go. Declarative YAML workflows; an LLM coordinator routes events through hub-and-spoke mailboxes. Three CLI verbs (flow / goal / agent) cover deterministic execution, dynamic planning, and one-shot agent calls. Use this when you need to run a multi-step LLM pipeline with branching, loops, conditions, retries, or persistence.
allowed-tools	Bash

zenflow

zenflow is a multi-agent workflow engine for Go. Workflows are declarative YAML; the engine is a DAG executor with an LLM coordinator that narrates progress and routes events between running steps through race-safe mailboxes. The Go SDK layer is goai - any provider goai supports works as a zenflow agent backend (Google, AWS Bedrock, Azure, OpenAI-compatible).

Install

One-line installer (Linux + macOS):

curl -fsSL https://zenflow.sh/install.sh | sh

Or via go install:

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

Or pull the Docker image:

docker pull ghcr.io/zendev-sh/zenflow:latest

The single Go binary has no runtime dependencies.

Three CLI verbs

Command	When
zenflow flow workflow.yaml	The plan is fixed up-front; you want a deterministic DAG execution.
zenflow goal "build a thing"	The plan must adapt to user input; the coordinator decomposes the goal into a workflow on the fly and runs it.
zenflow agent "<prompt>"	One-shot agent call with optional tool loop. Reuses zenflow's lifecycle hooks and provider routing.

zenflow flow - deterministic DAG

zenflow flow review.yaml --model gemini/gemini-3-pro-preview

Loads the YAML, validates, runs every step in dependency order. Failures cascade per options.onStepFailure.

zenflow goal - dynamic planning

zenflow goal "Refactor the auth module to use OAuth2" --model bedrock/anthropic.claude-sonnet-4-6

The coordinator LLM decomposes the goal into a workflow (agents + steps), validates it against the spec schema, and executes. Pass --plan to print the plan without running it.

zenflow agent - single-agent chat

zenflow agent "Summarise this repo's README" --model azure-deployment/gpt-5

A single agent loop with the configured tool catalog. Most useful for one-shot tasks that don't need multi-step coordination.

Provider env vars

Set the credentials for whichever provider you target:

Provider	Env var	Example model
Google Gemini	GEMINI_API_KEY	gemini/gemini-3-pro-preview
AWS Bedrock	AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (or AWS profile)	bedrock/anthropic.claude-sonnet-4-6, bedrock/minimax.minimax-m2.5
Azure (AI Services / OpenAI / Anthropic)	AZURE_OPENAI_API_KEY + AZURE_RESOURCE_NAME	azure-deployment/gpt-5, azure-deployment/claude-sonnet-4-6

The --model flag accepts the provider/model-id form. For Azure, deployment-based URLs are auto-resolved when the model id matches a known deployment family.

MCP tools

zenflow reads a Claude-compatible .zenflow/settings.json and exposes every declared MCP server's tools to agents. All three verbs use it; override with --mcp-config PATH, disable with --no-mcp.

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

Tools are namespaced <server>__<tool>; an agent's tools: list grants a whole server by its bare name (firecrawl) or one tool by its full name (firecrawl__scrape). stdio, HTTP, and SSE transports are supported, with ${VAR} env expansion.

YAML workflow shape

Minimum:

name: my-workflow

agents:
  writer:
    description: A concise technical writer.
    prompt: "Always reply in numbered bullet points."

steps:
  - id: draft
    agent: writer
    instructions: "Draft a 5-point summary of {{.context.input}}."

Add features as you need them:

• dependsOn: [otherStep] - DAG edges.
• condition: steps.draft.result.length > 100 - CEL expression; step is skipped when false.
• loop: - three flavours: forEach (iterate an array from a previous step's output), repeat-until (run a sub-DAG until an untilAgent returns done: true or a until CEL expression is true), outputMode: cumulative | last.
• include: subworkflow.yaml - compose sub-workflows; their step IDs are namespaced under the parent step.
• tool: read / toolInput: {path: $steps["prev"].content} - invoke a registered goai tool directly (no LLM call). String values in toolInput starting with $ are evaluated as CEL expressions. Available CLI tools: bash, read, write, glob, grep. Mutually exclusive with agent, instructions, loop, and include.
• resultSchema: { ... } - auto-injects a submit_result tool so the agent emits structured output.
• options: - maxConcurrency, onStepFailure: cascade | skip-dependents | abort, timeout, stepTimeout, isolation: worktree-per-step, scheduler: dependency-first | round-robin | least-busy.

Full reference: https://zenflow.sh/yaml.

NDJSON --json event schema

Every CLI verb accepts --json for line-delimited JSON output. Each event line carries:

Field	Type	Notes
type	string	Event type (see table below).
timestamp	RFC3339 string	Event clock.
runId	string	Workflow run ID; correlates events from the same run.
stepId	string	Step ID; absent for run-scoped events.
agent	string	Agent name; absent for non-agent events.
agentId	string	Per-call agent ID (set on streaming output events when the runner is namespaced).
message	string	Human-readable detail; semantics differ per event type.
duration	string	Go duration string ("1.234s"); set on completion events.
tokens	object	{prompt, completion, total} token counts; set on completion events.
error	string	Error string; set on failure events.
data	object	Event-type-specific payload (input args, output bytes, drop reasons, etc.).
delta	string	Streaming token delta. Only on output.
done	boolean	Streaming-end marker. Only on output.
reasoning	boolean	Set to true when the streaming delta is reasoning/thinking content (vs final agent text). Omitted otherwise.

Event types

type	Emitted when
workflow_start	Workflow run begins.
workflow_end	Workflow run ends (success or failure).
step_start	A DAG step begins.
step_end	A DAG step ends successfully.
step_skipped	A step skipped (failed dep with skip-dependents strategy, or false condition).
error	A step failed; subsequent dependents may cascade per options.onStepFailure.
agent_turn	The agent loop took a turn (LLM call). data.phase is request or response.
tool_call	A tool was invoked. data.phase is start or end.
message	An informational message (e.g. CEL skip reason, forEach item cap).
coordinator_narration	Coordinator's narrate(...) tool call.
coordinator_message	Coordinator's forward_to_agent(...) tool call.
coordinator_synthesis	Coordinator's finalize(summary=...) tool call.
coordinator_inbox_message	Reverse reply from a resumed step landed in the coordinator's inbox.
message_sent	An agent or coord-side outbound message was queued.
message_dropped	A router message was dropped before delivery. data.reason carries the typed reason.
agent_inbox_drain	An agent drained one router message into its LLM conversation.
agent_idle	The agent finished a goai iteration with no unread mailbox messages.
agent_wake	The agent woke from idle to drain new messages.
max_wake_cycles_warning	Wake-cycle cap is at 80% of configured limit.
resume_started	Auto-resume goroutine spawned for a terminated step that received a new router message.
resume_completed	Resume run finished with a final response.
resume_failed	Resume could not complete (ctx cancel, transcript cap, agent error).
resume_queued	A resume attempt arrived while another for the same step was already in flight.
transcript_sealed	Transcript Append hit the size cap; subsequent appends for the step are suppressed.
plan_ready	RunGoal decomposition produced a workflow. data.workflow carries the parsed *Workflow.
output	Streaming agent output token. Set delta, done, optionally reasoning.

The schema is additive: new event types may appear, existing types never reshape. Unknown type values are safe to skip.

Exit codes

Code	Meaning
0	Success.
1	Step or workflow failure.
2	Validation or coordinator-side error.
3	Configuration or usage error (missing argument, unknown flag, no LLM provider).
124	Hard-watchdog timeout. Fires when --timeout was set and the process did not unwind within timeout + 30s; goroutine stacks are dumped to stderr.

When to use which mode

You have a YAML workflow file already.       → zenflow flow workflow.yaml
You have a free-form goal in a string.       → zenflow goal "<goal>"
You have a one-shot agent prompt.            → zenflow agent "<prompt>"

You want deterministic, repeatable runs.     → zenflow flow
You want the coordinator to plan on the fly. → zenflow goal
You want to chain steps, conditions, loops.  → flow or goal (both support full YAML)
You only need a single LLM call.             → zenflow agent

You need to embed in Go code.                → import github.com/zendev-sh/zenflow
You need to script around the binary.        → use --json output (see schema above)

Embedding in Go

The same engine is exposed as a library:

import (
  "context"

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

func run(ctx context.Context) error {
  llm, _ := google.New(ctx, "gemini-3-pro-preview")

  orch := zenflow.New(
    zenflow.WithModel(llm),
    zenflow.WithStorage(zenflow.NewMemoryStorage()),
  )
  defer orch.Close()

  wf, err := zenflow.LoadWorkflow("review.yaml")
  if err != nil { return err }

  result, err := orch.RunFlow(ctx, wf)
  _ = result
  return err
}

49 With* orchestrator options + 22 WithRunner* agent options cover provider config, concurrency, timeouts, mailbox tuning, transcript caps, isolation, observability, and resume policies. Full reference: https://zenflow.sh/api.

Reference

• Full docs: https://zenflow.sh
• GitHub: https://github.com/zendev-sh/zenflow
• Spec: https://zenflow.sh/yaml and https://github.com/zendev-sh/zenflow/blob/main/spec/v1/spec.md