Language Overview
The shape of a .dip file — structure, header, and where each piece is documented.
File Structure
Every .dip file contains exactly one workflow. The top-level structure has up to five sections, in this order:
goal, requires, start, exit
model, provider, ...
key: value, ...
agent, human, tool, ...
A -> B when ...
Dippin uses indentation-sensitive syntax (like Python). Use 2 spaces or tabs consistently. The canonical formatter always outputs 2-space indentation.
Format Version (dip N)
A .dip file may optionally declare its format version on the first line, before the workflow declaration — e.g. dip 2. With no declaration the version defaults to 1, and the formatter only emits the dip N line for versions greater than 1 (a v1 file never gains one). The version is parsed before the workflow body so a format version can change edge syntax wholesale; dippin fmt --migrate converts a v1 file to dip 2 — a lossless version bump that keeps the retry channel on the node, relabeling fallback_target to its dip-2 spelling fallback_retry_target.
Workflow Header
The workflow declaration is the first line, followed by required and optional header fields:
workflow my_pipeline
goal: "Ask user for a task, implement it, review, ship"
start: AskUser
exit: Done| Field | Required | Description |
|---|---|---|
workflow <name> | Yes | Declares the workflow and its identifier |
goal: <text> | No | Human-readable objective for this pipeline |
requires: <id>[, <id>...] | No | Workflow-level declared prerequisites (advisory; comma-separated identifiers — tools, MCP servers, env vars). Mirrors node-level reads: / writes: for shape. |
start: <NodeID> | Yes | Entry point node — execution begins here |
exit: <NodeID> | Yes | Terminal node — execution ends here |
Vars Block
The optional vars block declares user-defined variables that are substituted wherever $key placeholders appear in prompts and commands.
vars
source_ref: "references/claude-agent-sdk-python/src"
target_name: claude-agents-rs
target_module: "claude-agents-rs/src/"Values can be quoted strings or bare identifiers. Keys must be unique — duplicate keys cause a parse error.
Vars are exported as graph-level DOT attributes so they round-trip through dippin export-dot and dippin migrate.
Where to go next
Each part of the language has its own reference page:
The 8 node kinds (agent, human, tool, parallel, fan_in, subgraph, conditional, manager_loop) and their common fields
Supported providers, the model catalog, and cost estimation