Concepts

Six terms you'll see repeatedly. Reading them in order takes about two minutes.

Workflow

A short YAML file with a name, a description, and a list of nodes. Workflows live either inside a project (.zen/workflows/) or globally on your machine (~/.zen/workflows/). When Z.E.N. starts, it scans both locations and registers every workflow it finds.

The bundled workflows that ship with Z.E.N. are a starting set you can copy, edit, or ignore. Most people delete what they don't use.

Node

One step in a workflow. The common types:

• prompt sends text to a provider and captures the response.
• bash runs a shell command and captures stdout/stderr.
• subagent delegates a chunk of work to a different model or a sub-workflow.
• approval pauses for a human reply before continuing.
• loop runs a body repeatedly with different inputs.

Every node has an id. Nodes that depend on other nodes list them under depends_on:, and Z.E.N. uses those dependencies to decide what runs in parallel and what waits. The shape of all those dependencies is called the DAG.

Run

One execution of a workflow. Runs get their own working directory, their own logs, their own database row. A run can succeed, fail, or be cancelled. A failed run can resume from the step that failed if the step is resumable.

You can see every run on the Dashboard. Click into one to read the logs and the output of each node.

Schedule

A recurring fire of a workflow. Pinned to a specific workflow inside a specific project. Driven by cron syntax with a timezone. The scheduler ticks every minute and fires anything that's due.

If a fire would step on a run that's still going, the schedule records the miss in skip_count and waits. If your machine was off when a fire was due, the next wake either skips ahead or replays, depending on the catch_up: setting.

Provider

The AI that runs a single node. Z.E.N. ships with Claude (via Claude Code SDK), Codex (via Codex SDK), and Pi as built-in providers. You choose the provider per node, not per workflow. One workflow can mix providers if that's what the work needs.

Swap a provider without rewriting the workflow. The node body stays the same; only the provider: field changes.

Agent

The external AI tool that dispatches Z.E.N. workflows for you. Claude Code, OpenClaw, Hermes, or any tool that speaks the same dispatch protocol. The agent lives outside Z.E.N. and asks Z.E.N. to fire workflows by name.

Provider and agent are easy to confuse and worth keeping straight: the provider runs a node inside a workflow, the agent asks Z.E.N. to run the workflow in the first place.

Less common terms

You'll see these eventually:

• Codebase. A project Z.E.N. knows about, identified by a name and a working path.
• Worktree. Optional. A git working copy created for runs that touch git; off by default for workflows that don't, opt in with worktree.enabled: true.
• Hook. A workflow that fires automatically on a system event (a webhook, a tool result).
• MCP server. A tool surface a node can call, defined elsewhere and registered with Z.E.N.
• Skill. A bundle of prompt plus tools plus examples your agent can invoke by name.

Each has a page if you need it. Most people never touch loops or hooks. Read the Run, Schedule, and Build sections; ignore the rest until something specific sends you to it.