This page is a glossary. The terms below show up everywhere else in the docs and in the UI. Skim it once, then come back when something is unclear. Each entry links out to the page with the full story.
Workflow#
A workflow is a YAML file describing a finite state machine: a set of steps
and the rules for moving between them. It declares those steps and the
transitions between them, plus a single initial state where execution starts.
Workflows are pure data on disk. Roscoe reads them at runtime, so you can edit a
file and re-run without rebuilding.
See YAML structure for the full schema.
State / Node#
A state (also called a node) is a single executable step inside a workflow. The two terms are interchangeable: the YAML calls them states, and the web editor draws them as nodes on a graph. The node types are:
script— run JavaScript or TypeScript on Bun (shell commands too, viaBun.$).ai_agent— call a model with a prompt.ai_judge— call a model with a rubric and parse a verdict.consensus— fan out to several sub-runs and vote.round_robin— judge candidates head-to-head and pick a winner.map— run the same step over a list and collect the results.condition— branch on context variables without calling out to anything.human— pause until a person approves or rejects.subworkflow— run another workflow as one step.end— terminate the run with an outcome.
Transition / Edge#
A transition is a named outgoing path from a state, declared under that
state's on: map. When a node finishes, its validator returns a transition key,
a string like 'true', 'pass', or 'high'. Roscoe looks up that key in on:
and runs the state it points to. If the key isn't present, the run fails.
Transition keys come from the node's validator, where you define which keys a node can emit.
Run#
A run is one execution of a workflow. Every run has a unique id, a start/end timestamp, and an outcome. Its per-node trace records every state visited, the inputs and outputs, and the transition taken. Runs are persisted to SQLite and visible in the web UI indefinitely.
Context / Variables#
Context is the key-value bag that flows through a run. Initial values come
from the CLI's --var key=value flags or the API's context field on
POST /api/runs. Each node can read context variables in its prompt or script.
Each node's outputs merge back into context, so downstream nodes can use them.
See output chaining for how to thread one node's output into the next.
Validator#
A validator turns a node's output into a transition key. The output can be a returned value, stdout, or an AI response. The common kinds are:
boolean— emits'true'or'false'. The default for script nodes (a truthy vs falsy return value) and yes/no judges.enum— picks from a fixed list of strings, e.g.['pass', 'fail', 'needs-review'], for multi-way branching.confidence— buckets a numeric score into named tiers such ashigh,medium, andlow.
Consensus nodes add two of their own, answer and most_consistent, for
tallying votes across the panel. See validators
for the full reference.
Outcome#
The outcome is the terminal status of a run, set by whichever end node
the workflow reaches. Three values: success, failure, cancelled. The
outcome drives the colour of the run row in the UI and the exit code of
roscoe run.
Workflow source#
Workflows live in one of two places. Global workflows sit in
~/.roscoe/workflows/ and are available everywhere you run roscoe. Project
workflows sit in <repo>/.roscoe/workflows/ and are scoped to that repo.
When both define a workflow with the same name, project shadows global. This lets you check workflow definitions into a repo and override anything that conflicts with a global one.
See workflow sources for resolution rules.
Execution mode#
Roscoe runs in one of two modes, depending on who orchestrates the AI calls. In
standalone mode the runner calls AI executors directly. This needs an
ANTHROPIC_API_KEY or a working claude CLI on the PATH, and it's the default
for roscoe run and the web UI. In MCP (Model Context Protocol) mode Claude
Code is the orchestrator. Roscoe runs as an MCP server, and Claude Code reads
each AI node's prompt, calls the model, and feeds the response back. Roscoe needs
no API key of its own.
See MCP integration.
LLM backend#
In standalone mode, Roscoe picks one of two LLM backends for its AI calls.
The SDK backend uses the Anthropic SDK with an API key from the environment;
it's faster and supports streaming and tool use. The CLI backend shells out
to claude -p as a subprocess, which needs no API key if you're already signed
in to Claude Code.
The backend is auto-detected: SDK if ANTHROPIC_API_KEY is set, CLI
otherwise. You can pin it explicitly in roscoe.yaml.
See LLM backends.
Where to next#
- Write your first workflow — build and run one end to end.
- YAML structure — the full schema behind these terms.