comanda

COMandA

Declarative AI pipelines for the command line. Define LLM workflows in YAML, run them anywhere, version control everything.

# Pipe code through multiple AI agents
cat main.go | comanda process code-review.yaml

# Compare how different models solve a problem
comanda process model-comparison.yaml

# Run Claude Code, Codex, and Gemini CLI in parallel
echo "Design a REST API" | comanda process multi-agent/architecture.yaml

Why comanda?

For AI-powered development workflows:

• Run Claude Code, OpenAI Codex, and Gemini CLI side-by-side
• Chain multiple agents for code review → test generation → documentation
• Get diverse perspectives on architecture decisions

For reproducible AI pipelines:

• YAML workflows you can version control and share
• Same workflow runs locally, in CI, or on a server
• Switch providers without changing your pipeline

For command-line power users:

• Pipes, redirects, scripts—works like grep or jq
• Process files, URLs, databases, screenshots
• Batch operations with wildcards and parallel execution

Quick Start

Install

# macOS
brew install kris-hansen/comanda/comanda

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

# Or download from GitHub Releases

Ensure the Go install location is on your PATH (often $(go env GOPATH)/bin or $(go env GOBIN)), then verify:

comanda --version

Configure

comanda configure
# Select providers (OpenAI, Anthropic, Google, Ollama, Claude Code, etc.)
# Enter API keys where needed

Run Your First Workflow

Create hello.yaml:

generate:
  input: NA
  model: gpt-4o
  action: Write a haiku about programming
  output: STDOUT

comanda process hello.yaml

Multi-Agent Workflows

Run multiple agentic coding tools in parallel and synthesize their outputs:

parallel-process:
  claude-analysis:
    input: STDIN
    model: claude-code
    action: "Analyze architecture and trade-offs"
    output: $CLAUDE_RESULT

  gemini-analysis:
    input: STDIN
    model: gemini-cli
    action: "Identify patterns and best practices"
    output: $GEMINI_RESULT

  codex-analysis:
    input: STDIN
    model: openai-codex
    action: "Focus on implementation structure"
    output: $CODEX_RESULT

synthesize:
  input: |
    Claude: $CLAUDE_RESULT
    Gemini: $GEMINI_RESULT
    Codex: $CODEX_RESULT
  model: claude-code
  action: "Combine into unified recommendation"
  output: STDOUT

echo "Design a real-time collaborative editor" | comanda process architecture.yaml

Supported Agents

No API keys needed for these—they use their own CLI authentication.

Common Use Cases

Code Review Pipeline

review:
  input: "src/*.go"
  model: claude-code
  action: "Review for bugs, security issues, and improvements"
  output: review.md

Data Analysis

comanda process analyze.yaml < quarterly_data.csv

Model Comparison

parallel-process:
  gpt4:
    input: NA
    model: gpt-4o
    action: "Write a function to parse JSON"
    output: gpt4-solution.py

  claude:
    input: NA
    model: claude-3-5-sonnet-latest
    action: "Write a function to parse JSON"
    output: claude-solution.py

compare:
  input: [gpt4-solution.py, claude-solution.py]
  model: gpt-4o-mini
  action: "Compare these implementations"
  output: STDOUT

Agentic Loops

Iterate until the LLM decides work is complete:

implement:
  agentic_loop:
    max_iterations: 5
    exit_condition: llm_decides
  input: STDIN
  model: claude-code
  action: |
    Iteration {{ loop.iteration }}.
    Previous: {{ loop.previous_output }}

    Implement and refine. Say DONE when complete.
  output: STDOUT

echo "Write a binary search function with tests" | comanda process implement.yaml

Agentic Tool Use

Enable Claude Code's full tool capabilities (Read, Write, Edit, Bash) within agentic loops:

explore:
  agentic_loop:
    max_iterations: 3
    exit_condition: llm_decides
    allowed_paths: [./src, ./tests]  # Enable tool access to these directories
    tools: [Read, Glob, Grep]        # Restrict to read-only tools
  input: STDIN
  model: claude-code
  action: |
    Explore the codebase and answer: {{ loop.previous_output }}
    Say DONE when you have the answer.
  output: STDOUT

Without allowed_paths, Claude Code runs in print-only mode. The tools option restricts available tools for safety.

Server Mode

Turn any workflow into an HTTP API:

comanda server
curl -X POST "http://localhost:8080/process?filename=review.yaml" \
  -d '{"input": "code to review"}'

Features

Visualize Workflows

See the structure of any workflow at a glance:

comanda chart workflow.yaml

+================================================+
| WORKFLOW: examples/parallel-data-processing... |
+================================================+

+------------------------------------------------+
|            INPUT: examples/test.csv            |
+------------------------------------------------+
                        |
                        v
+================================================+
| PARALLEL: parallel-process (3 steps)           |
+------------------------------------------------+
  +----------------------------------------------+
  | [OK] analyze_csv                             |
  | Model:  gpt-4o-mini                          |
  | Action: Analyze this CSV data and            |
  +----------------------------------------------+
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  +----------------------------------------------+
  | [OK] extract_entities                        |
  | Model:  gpt-4o-mini                          |
  | Action: Extract all named entities           |
  +----------------------------------------------+
+================================================+
                        |
                        v
+------------------------------------------------+
| [OK] consolidate_results                       |
| Model:  gpt-4o                                 |
| Action: Create a comprehensive data analysis   |
+------------------------------------------------+

                        |
                        v
+------------------------------------------------+
|     OUTPUT: comprehensive-report.txt           |
+------------------------------------------------+

+================================================+
| STATISTICS                                     |
|------------------------------------------------|
| Steps: 4 total, 3 parallel                     |
| Valid: 4/4                                     |
+================================================+

Documentation

• Examples — Sample workflows for common tasks
• Multi-Agent Workflows — Claude Code + Codex + Gemini CLI patterns
• Claude Code Examples — Agentic coding workflows
• Agentic Loops — Iterative refinement workflows
• Tool Use Guide — Execute shell commands in workflows
• Server API — HTTP endpoints reference
• Configuration Guide — Adding models and providers

Installation Options

Homebrew (macOS)

brew install kris-hansen/comanda/comanda

Go Install

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

Remote Install (Go)

Install directly on a remote host over SSH:

ssh user@host 'GOBIN=$HOME/bin go install github.com/kris-hansen/comanda@latest'
ssh user@host 'export PATH="$HOME/bin:$PATH"; comanda --version'

If you already manage Go on the remote host, you can omit GOBIN and rely on the default $(go env GOPATH)/bin in your PATH.

Pre-built Binaries

Download from GitHub Releases for Windows, macOS, and Linux.

Build from Source

git clone https://github.com/kris-hansen/comanda.git
cd comanda && go build

Configuration

Provider Setup

comanda configure

Interactive prompts for:

• Provider selection (OpenAI, Anthropic, Google, X.AI, Ollama, vLLM)
• API keys
• Model names and capabilities

Agentic CLI Tools

These use their own authentication—no comanda configuration needed:

# Claude Code
claude --version  # Verify installed

# Gemini CLI
gemini --version

# OpenAI Codex
codex --version

Environment File

Configuration stored in .env (current directory) or custom path:

export COMANDA_ENV=/path/to/.env

Encryption

Protect your API keys:

comanda configure --encrypt

Development

make deps      # Install dependencies
make build     # Build binary
make test      # Run tests
make lint      # Run linter
make dev       # Full dev cycle

See CONTRIBUTING.md for contribution guidelines.

License

MIT — see LICENSE

Acknowledgments

• OpenAI, Anthropic, and Google for their APIs
• Ollama and vLLM for local model support
• The Go community