Comanda

Comanda defines and runs LLM workflows as YAML pipelines. Use it to generate workflows, inspect charts, edit workflow YAML, run workflows, improve workflows, orchestrate multiple models, and build agentic loops.

Core commands

comanda generate workflow.yaml "Create a workflow that summarizes Markdown files"
comanda chart workflow.yaml
comanda process workflow.yaml
cat input.txt | comanda process workflow.yaml
comanda improve workflow.yaml "Make it output risks and action items"
comanda configure
comanda version

Useful execution flags:

comanda process workflow.yaml --runtime-dir ./data --vars name=value --debug

Workflow editing rules

For detailed YAML patterns, read references/WORKFLOW-SPEC.md before creating or changing non-trivial workflows.

Minimal step:

summarize:
  input: STDIN
  model: gpt-4o
  action: "Summarize the input."
  output: STDOUT

Critical data-flow rule

For ordinary step-to-step data flow, use only:

1. output: STDOUT followed by next step input: STDIN
2. explicit files: output: ./file.json followed by input: ./file.json

Do not use $VARIABLE syntax for ordinary step chaining. as $var is only input aliasing inside the same step's action prompt.

# Good: same-step input aliasing
compare:
  input: old.md as $baseline
  model: gpt-4o
  action: "Compare the current input with $baseline."
  output: STDOUT

# Bad: not valid step-to-step flow
step1:
  output: STDOUT as $data
step2:
  input: $data

For parallel fan-in, write branch outputs to files and combine from those files. For defer/branching, have the prior step emit JSON with step_name and input; the selected branch reads STDIN.

Tool steps

Use shell tools only in trusted workflows. Prefer tool: allowlists; tool_config: examples in older docs are stale for step-level allowlists.

list_go_files:
  input: "tool: find . -name '*.go' -type f"
  model: NA
  tool:
    allowlist: [find]
    timeout: 30
  action: NA
  output: STDOUT

Agentic workflows

Default to linear workflows. Use agentic_loop only when work truly needs iteration until quality/completion. Prefer file outputs such as .comanda/result.md, grant explicit allowed paths, and tell the agent to read/update existing files across iterations. Use comanda loop status/resume/cancel/clean for long-running loops.

Loop-specific input_state/output_state variables are valid only inside agentic-loop/multi-loop orchestration; they are not ordinary workflow step variables.

Models and examples

Common model IDs include gpt-4o, claude-sonnet-4-20250514, gemini-pro, grok-4-1-fast-reasoning, grok-4-1-fast-non-reasoning, ollama/<model>, claude-code, gemini-cli, and openai-codex. Run comanda configure for API keys.

Examples live in ~/clawd/comanda/examples/:

• parallel-processing/ — file-based parallel fan-in
• tool-use/ and security/ — shell tool input/output patterns
• agentic-loop/ — iterative and multi-loop workflows
• codebase-index/ — index capture and reuse
• file-processing/ — chunking, batching, wildcards
• model-examples/ — provider/model examples

Troubleshooting

• Validation/structure: comanda chart workflow.yaml --verbose
• Execution details: comanda process workflow.yaml --debug
• Missing keys: comanda configure
• Blocked tool command: add the command to the step's tool.allowlist