Appearance
The Big Picture: Welcome to Z.E.N.
Think of this system as an invisible kitchen manager. It doesn't cook the food itself, but it hands out the recipes, tells the cooks when to start, watches the clock, and makes sure the appetizers go out before the main course.
To understand how it works, you only need to know seven basic ideas.
1. Workflow: The Recipe Book
A workflow is a recipe. It is a short text file where you write down the name of the dish, a description of what it is, and the exact steps needed to make it.
You can keep these recipes in two places: in the kitchen drawer for a specific project, or in your personal cookbook at home so you can use it anywhere on your machine. Every time the system starts, it looks in both places to see what recipes are available. It comes with a few basic starter recipes, but you can copy them, change them, or throw them in the trash if you do not need them.
2. Node: The Individual Steps
A node is a single step inside your recipe. Just like a kitchen recipe tells you to chop onions or bake for twenty minutes, a step here tells the system to do one specific action.
The main types of steps are:
- Prompt: Ask a smart assistant a question and wait for the answer.
- Bash: Give a direct command to the computer, like telling it to move a file.
- Agent: Hand the step to an agent runtime that decides on its own what tools to use and how. The runtime drives the loop; you give it a goal, not a recipe.
- Tool: Call one specific known tool directly with structured inputs. No AI involved — predictable, fast, debuggable.
- Subagent / Workflow: Open up another recipe inside this one (a workflow within a workflow).
- Approval: Pause everything and wait for a human to say it is okay to keep going.
- Loop: Repeat the same step over and over with different ingredients.
Because some steps cannot happen until others are finished (you cannot bake the cake until you mix the batter), each step lists what it depends on. The system looks at these connections to figure out what steps can be done at the exact same time, and what steps have to wait in line.
3. Run: Cooking the Meal
A run is what happens when you actually execute the recipe. If a workflow is the blueprint for chocolate cake on paper, a run is the actual cake baking in the oven right now.
Every single run is isolated. It gets its own counter space, its own mixing bowls, and its own record log. If a run fails because the power blinked, you do not have to start over from scratch. You can restart it right from the step where it broke. You can watch all of this happening in real-time on a digital dashboard, clicking into any active meal to see exactly what is happening.
4. Schedule: The Alarm Clock
A schedule is an automated timer pinned to a specific recipe. It tells the manager to make a certain dish every Tuesday at 4:00 PM. The manager checks the clock every minute to see if anything is due.
If the timer goes off but the kitchen is still busy making that exact same dish from earlier, the manager notes the conflict and waits. If your computer was turned off when the timer was supposed to go off, you can set it to either skip that meal entirely or hurry up and play catch-up the moment the computer turns back on.
5. Provider / Harness: The Line Cooks
The provider is the specific AI brain doing the actual work for a single step — Claude, Codex, Pi, Gemini, Hermes. The technical word is "harness" (the thing that drives the AI from inside Z.E.N.); both words mean the same thing in the YAML, the UI calls it provider, the logs call it harness. Don't worry about which word.
The clever part is that you choose the brain per step, not per recipe. You can have a smart slow brain write a letter in step one, and a fast cheap brain double-check the spelling in step two. If a new, better brain comes out tomorrow, you swap one word.
Open Settings → Harnesses to see which brains are wired up. Each shows whether it's healthy, what version it's running, and what it can do (call tools, resume sessions, control cost, etc.).
6. Tool & Connector: The Pantry
A tool is one specific action a step can take — "list my unread Gmail", "search Notion", "run this CLI". Tools live in a registry. A connector is the bundle that brings a group of tools into the registry — install the Gmail connector and dozens of tools appear automatically.
You add tools by adding connectors. You add connectors by dropping a small text file in your ~/.zen/connectors/ folder, or by installing an MCP server with one command. No code changes, no rebuilds. Settings → Connectors and Settings → Tools show what's currently wired up.
7. Calling Agent: The Head Chef
The calling agent is an external AI — Claude Code in your terminal, an OpenClaw window, whatever — that decides to order a recipe. It lives outside Z.E.N. entirely. It looks at the big picture and tells Z.E.N. "run this recipe now."
To keep all three straight:
- The calling agent stands outside the kitchen and orders the dish.
- The harness is the brain inside the kitchen doing the cognitive work for one step.
- A tool is a piece of equipment that brain can pick up to do the work.
Terms You Can Ignore for Now
As you get deeper into the system, you might bump into a few other words. Do not worry about memorizing these yet, as most people rarely need them:
- Workspace: The specific digital folder where your project or recipe context lives.
- Worktree: A safety feature that makes a temporary copy of your files so an AI does not accidentally overwrite your real work while experimenting.
- Hook: An automated trigger that fires a recipe the instant something happens outside, like a customer submitting a form.
- MCP Server: A specific kind of tool bundle (see Concept 6) that speaks the Model Context Protocol — Notion, Slack, GitHub, lots of others.
- ACP / SDK / CLI: Three different ways a harness can talk to its AI brain under the hood. The YAML doesn't care which; Settings → Harnesses shows the transport for each.
- Session: When an agent step is mid-conversation with its brain, that conversation has an id you can resume in a later step.
- Skill: A pre-packaged how-to bundle the calling agent reads before doing something — e.g. "wire a new CLI into Z.E.N." Bundled skills ship with Z.E.N.; you can drop your own in
~/.zen/commands/.
The best approach is to avoid learning all of this at once. Look at how a run works, set up a schedule, and start building. Skip the complicated loops and tripwires until you find yourself trying to solve a problem that absolutely requires them.