comanda

Make coding agents earn their exit.

Comanda is the terminal-native runtime for durable, self-improving agent work in a repository. Describe a workflow in English, inspect the generated program, run the coding agents you already use, and stop only when your own quality gates say the work is done.

From an idea to a governed workflow

Comanda starts with English, but ends with a YAML program you can inspect, version, and improve.

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

# Inspect the generated workflow as a graph
comanda chart feature-loop.yaml --format mermaid

# Run it in your repository
comanda process feature-loop.yaml

# Evolve the program with plain-English feedback
comanda improve feature-loop.yaml \
  "Add a Codex reviewer and require typecheck before completion"

Describe it. Inspect it. Run it. Improve it. Commit it.

A loop does not finish because an agent says “DONE”

Long-running work needs an observable exit criterion. Comanda's agentic loops persist state, refine subsequent prompts from prior results, and run automated quality gates after each iteration. Interrupt a run and resume it from its last checkpoint.

agentic-loop:
  config:
    name: code-quality-improvement
    stateful: true
    checkpoint_interval: 2
    max_iterations: 10
    prompt_improvement:
      enabled: true
    quality_gates:
      - name: syntax-check
        type: syntax
        on_fail: abort
      - name: tests
        command: "make test"
        on_fail: retry
    allowed_paths: ["./src", "./tests"]

Run the complete code-quality loop, then inspect or resume it:

comanda process examples/agentic-loop/code-quality-loop.yaml
comanda loop status code-quality-improvement
comanda loop resume code-quality-improvement

Comanda supports retry, abort, and skip policies; syntax, security, and custom-command gates; bounded or indefinite runs; and creator/checker or dependent multi-loop workflows. See agentic-loop examples.

Use the agents you already have

Coordinate Claude Code, Gemini CLI, OpenAI Codex, Kimi Code, API models, and local models in one workflow. Give agents distinct roles, pass work through files or standard input/output, and keep the results visible in your repository.

parallel-process:
  architecture:
    input: STDIN
    model: claude-code
    action: "Review the design and identify implementation risks."
    output: .comanda/architecture-review.md

  implementation:
    input: STDIN
    model: openai-codex
    action: "Review the implementation plan and identify practical risks."
    output: .comanda/implementation-review.md

synthesize:
  input:
    - .comanda/architecture-review.md
    - .comanda/implementation-review.md
  model: gemini-cli
  action: "Produce one prioritized recommendation."
  output: STDOUT

Run this exact parallel-review workflow with git diff | comanda process examples/multi-agent/parallel-review.yaml, or explore multi-agent workflows and parallel processing.

Keep agent work inside the repository model

• Git worktrees — run parallel implementations in isolated branches, then inspect and compare their diffs.
• Codebase indexes — capture repository structure, symbols, conventions, operational notes, and risk areas for later agent work; incrementally update or diff an index as the code changes.
• Explicit boundaries — constrain agentic loops to allowed paths and named tools.
• Quality gates — use your own tests, linters, and security checks as the definition of done.

comanda index capture --enhance
comanda index diff my-project
comanda index update my-project

See codebase-index examples.

Build a workflow once. Run it everywhere.

Workflows are plain files. Review them in pull requests, run them from the terminal or CI, serve them over HTTP, or expose them to MCP clients.

# Expose checked-in workflows as MCP tools and skills as MCP prompts
comanda mcp

# Run a workflow as part of a shell pipeline
git diff | comanda process review.yaml

See the MCP server guide, server API, and skills examples.

Why Comanda?

Comanda sits between a coding agent and an agent framework: it turns agent work into a durable, reviewable program that runs where developers already work.

Install

# macOS
brew install kris-hansen/comanda/comanda

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

See GitHub Releases for prebuilt binaries for macOS, Linux, and Windows.

More capabilities

• Generate and improve workflows from natural-language feedback
• Render workflow structure as terminal or Mermaid graphs with validation
• Process files, URLs, images, PDFs, databases, and batches with chunking
• Use shell tools with explicit allowlists
• Call OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, Sakana, Ollama, vLLM, llama.cpp, and compatible providers
• Run workflows as HTTP endpoints or OpenAI-compatible server routes

Browse all examples or visit comanda.sh for documentation and templates.

Development

make deps
make build
make test

License

MIT

Download History