kris-hansen/comanda: Declarative YAML Workflows for Coding Agents

The problem Comanda solves is the missing exit criterion

A coding agent that prints DONE has not necessarily finished. Comanda's README puts the motivation plainly: a loop should not finish because an agent says it is done. The project targets repository work that spans more than one agent invocation, where the definition of done is a test suite, a linter or a security check rather than a sentence in a chat transcript.

The intended user is an engineer who already runs Claude Code, Codex, Gemini CLI or Kimi Code from a terminal and wants the orchestration around them to be a file under version control. Comanda deliberately does not try to be an agent framework for building an AI product, and its own comparison table routes that need to LangGraph, CrewAI or an SDK. It also does not replace a single agent CLI for a single task. The space it claims is between those two.

How a Comanda workflow is structured and executed

A workflow is a YAML file whose top-level keys are step names. Each step declares an `input`, a `model`, an `action` and an `output`. Inputs can be the literal `STDIN`, a file path, or a list of files from earlier steps. Outputs can be a file path or `STDOUT`. That is the entire data flow: agents do not share memory, they share files and pipes.

The README's parallel-review example makes the shape concrete. An `architecture` step and an `implementation` step both read `STDIN` and write separate markdown files under `.comanda/`, and a `synthesize` step takes both files as a list input and writes to `STDOUT`. Because the intermediate results are files in the repository, they can be diffed, reviewed and committed like any other artifact.

The agentic-loop construct adds state on top of that. With `stateful: true` the run persists checkpoints, and `checkpoint_interval: 2` controls how often. `prompt_improvement` feeds prior results back into subsequent prompts. `quality_gates` run after each iteration by default, with `on_fail` set to `abort`, `retry` or `skip`. A gate can be a `syntax` check, a security check, or a `command` such as `make test`. Setting `quality_gates_before_steps: true` moves validation ahead of the step instead, which matters when deterministic gates prepare files the loop's first step consumes.

Installing Comanda and running a first workflow

The README lists two install paths. On macOS, Homebrew taps the maintainer's formula. With a Go toolchain, `go install` pulls the module directly. Prebuilt binaries for macOS, Linux and Windows are published on GitHub Releases.

brew install kris-hansen/comanda/comanda
go install github.com/kris-hansen/comanda@latest

After installing, the fastest way to see the mechanism is to generate a workflow from a sentence rather than write YAML by hand. The README's first example describes an outcome and writes it to a file:

comanda generate feature-loop.yaml \
  "Implement this feature until tests and security checks pass"

The generated file is the artifact, not the prompt. Before running it, render it as a graph to confirm the steps and their wiring are what you meant:

comanda chart feature-loop.yaml --format mermaid
comanda process feature-loop.yaml

`comanda chart` with `--format mermaid` emits a diagram of the workflow's structure, and the README says it also validates. `comanda process` executes the file in the current repository. For the multi-agent case, the README pipes a diff into a checked-in workflow, which is the pattern to copy if you want review output tied to a change set:

git diff | comanda process examples/multi-agent/parallel-review.yaml

Once a workflow runs, `comanda improve` takes plain-English feedback and rewrites the YAML rather than the prompt, so the change is reviewable in a pull request.

Where the agentic loop configuration gets awkward

The loop is the feature that justifies the tool, and it is also where the configuration surface is largest. A working loop needs `stateful`, `checkpoint_interval`, `max_iterations`, `prompt_improvement`, `quality_gates` and `allowed_paths` to be mutually consistent. `allowed_paths` is the boundary that keeps an agent inside `./src` and `./tests`; get it wrong and the loop either stalls on a write it cannot make or is scoped wider than intended. The README does not document what happens when a gate command is missing from the environment, so a loop pointed at a `make` target that does not exist is a failure mode to test deliberately rather than assume.

Bounded and indefinite runs are both supported, which is a genuine trade-off rather than a feature list. An indefinite loop with `prompt_improvement` enabled can drift in a direction no gate catches, because the gates only check what you told them to check. The README does not describe a rollback mechanism for a loop that has already written files, so recovery depends on Git rather than on Comanda. If your work cannot tolerate that, the loop is the wrong construct and a single `comanda process` step is the safer choice.

Comanda compared with running an agent CLI directly

The honest alternative is not another orchestrator. It is the agent's own CLI. If you want Claude Code to implement one feature, running Claude Code is fewer moving parts than writing a YAML file that invokes Claude Code. Comanda's own comparison table says as much, routing that case to the native CLI.

The difference in approach appears as soon as the work needs more than one agent or more than one attempt. A native CLI session is interactive and its state lives in that session. A Comanda workflow is a file: the model assignments (`claude-code`, `openai-codex`, `gemini-cli`), the file handoffs and the gate commands are all declared, so a reviewer can see which agent reviewed which artifact. The second difference is resumability. The README states that an interrupted run can be resumed from its last checkpoint, with `comanda loop status` and `comanda loop resume` operating on the loop by its configured `name`. A native CLI does not give you a named, queryable run state.

Maintenance, licensing and what a version bump costs you

Comanda is MIT licensed, so the usual obligations apply: keep the copyright notice and the licence text with any redistribution. Nothing in the repository suggests a dual licence or a commercial tier, but that is a statement about what is visible, not legal advice.

The release cadence is high. Three releases are listed within the week before the last push on 2026-09-09: v0.0.238 and v0.0.239 on 2026-09-05, and v0.0.240 on 2026-09-09. The version numbers are still in the 0.0.x range, which is worth weighing if you pin Comanda in CI. A workflow file that runs today may need editing after a minor bump, and the repository's own `basic-workflow.yaml` and `examples/` tree are the reference for what the current schema accepts. The Makefile exposes `make lint`, `make test` and `make build`, so building from source and running the test suite before upgrading is a short loop rather than a project.

Memory, indexing and the parts that are opt-in

Two capabilities run alongside the workflow engine. The first is durable semantic memory. Setting `memory: true` keeps the original behaviour of injecting the configured `COMANDA.md` file in full. A `memory:` mapping switches to bounded recall from a SQLite FTS5 database, scoped to a namespace, with each recalled record keeping a durable ID and a source reference. Records are added and searched from the CLI:

comanda memory add --namespace project --type decision \
  --source architecture-2026-07 "Use SQLite FTS5 for local durable-memory retrieval."
comanda memory search --namespace project "local memory retrieval"

The second is the codebase index, which captures repository structure, symbols and conventions and can be updated or diffed as code changes. Both are additive: a workflow that never sets `memory` and never calls `comanda index` behaves as it did before. That is the right default, and it also means neither feature will help you unless you deliberately wire it into a step.

Editorial conclusion

Adopt Comanda if your agent work already happens in a repository and you want the workflow itself committed, reviewed and resumed rather than retyped. Skip it if you only ever hand one task to one CLI, since the YAML layer adds nothing there. Before trusting a loop in CI, run `comanda chart` on the generated file, confirm the `allowed_paths` list matches the directories the loop is actually supposed to touch, and check that every gate command in the `quality_gates` block exists in your Makefile. The exit criterion is the whole point of the tool, so verify it fires on a deliberately failing run before you let it gate anything.

Frequently asked questions

Official sources

1. kris-hansen/comanda on GitHub
2. License: MIT
3. Project website
4. README
5. Releases