Features — comanda

🔀 Multi-Agent Orchestration#

Run Claude Code, OpenAI Codex, Gemini CLI, and Kimi Code in parallel. Get diverse perspectives from multiple AI models and synthesize them into unified recommendations.

architecture-review.yaml

parallel-process:
  claude-analysis:
    input: STDIN
    model: claude-code
    action: "Analyze architecture and trade-offs"
            output: ./results/claude.md

  gemini-analysis:
    input: STDIN
    model: gemini-cli
    action: "Identify patterns and best practices"
            output: ./results/gemini.md

  codex-analysis:
    input: STDIN
    model: openai-codex
    action: "Focus on implementation structure"
            output: ./results/codex.md

synthesize:
  input: [./results/claude.md, ./results/gemini.md, ./results/codex.md]
  model: claude-code
  action: "Combine into unified recommendation"
  output: STDOUT
          

⊞ Comanda as an MCP Server#

Turn the workflows you already keep in Git into on-demand tools for MCP-native agents. Start comanda mcp, then Claude Code, Codex, Kimi Code, or Cursor can discover and call them without carrying every workflow instruction in their working context.

Workflows → tools

Every discovered YAML workflow becomes a callable MCP tool. Its first comment becomes the description, and {{ var }} placeholders become optional string inputs.

Skills → prompts

Comanda skills appear as argumented MCP prompts. The agent can fetch the rendered instruction when it needs it—no model call required.

One workflow surface

Serve over stdio for local clients or streamable HTTP on trusted localhost. Workflows execute through Comanda's existing processor and return their final output as tool results.

workflows/release-notes.yaml

# Turn a git diff into release notes for {{ audience }}
release_notes:
  input: STDIN
  model: gpt-5.6-terra
  action: |
    Write clear {{ audience }} release notes from the supplied git diff.
    Lead with user impact; include breaking changes and upgrade steps.
    Do not invent changes.
  output: STDOUT
          

Connect an agent

# Claude Code or Codex: expose every workflow in this directory
$ claude mcp add comanda -- comanda mcp --dir ./workflows
$ codex mcp add comanda -- comanda mcp --dir ./workflows

# The agent now sees release_notes(input, audience) as a tool.
# It calls it only when it needs release notes—not on every turn.
          

Why MCP instead of one giant agent prompt? Keep reusable procedures versioned, reviewable, and shared across agents and repositories. Agents retain room for the task at hand, while each workflow gets a clear tool contract and a reproducible execution path. Only expose trusted workflows: they run with the permissions of the user who starts the server, including any shell tools they define.

Workflows are discovered from ~/.comanda/workflows/, .comanda/workflows/, or explicit --dir and --workflow flags. Skills are exposed as prompts by default; pass --no-skills to disable them.

🔁 Agentic Loops#

Iterative refinement until the LLM decides work is complete. Perfect for code generation, document writing, and any task that benefits from self-improvement.

iterative-implementation.yaml

implement:
  agentic_loop:
    max_iterations: 5
    exit_condition: llm_decides
    allowed_paths: [./src, ./tests]
    tools: [Read, Write, Edit, Bash]
  input: STDIN
  model: claude-code
  action: |
    Iteration {{ loop.iteration }}.
    Previous: {{ loop.previous_output }}

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

Smart defaults: If you omit allowed_paths, comanda auto-infers them from the workflow directory and common project subdirectories (src, lib, test, docs, build). Simple workflows "just work" without explicit configuration.

🧠 Self-Improving Loops#

Agentic loops can refine their own prompt between iterations. The latest result feeds a prompt-improvement pass, then the next iteration runs with a tighter, more specific instruction through {{ loop.current_prompt }}.

self-improving-loop.yaml

draft-and-refine:
  input: STDIN
  model: claude-code
  agentic_loop:
    max_iterations: 5
    exit_condition: llm_decides
    prompt_improvement:
      enabled: true
      instructions: |
        Tighten the next prompt using the latest result.
        Preserve what worked, remove ambiguity, and make
        the next pass more specific and actionable.
  action: |
    {{ loop.current_prompt }}

    Previous result:
    {{ loop.previous_output }}

    Improve the output. Say DONE when it is ready.
  output: draft.md
          

Use this for long-form writing, code improvement, research synthesis, prompt tuning, or any workflow where each pass should learn from the last instead of simply retrying the same instruction.

♻️ Improve Existing Workflows#

comanda improve edits an existing YAML workflow from plain-English feedback, validates the generated workflow, and retries with validation errors when needed. It is the fastest path from a rough pipeline to a cleaner, more agentic one.

Terminal

# Break a workflow into more explicit steps
$ comanda improve workflow.yaml "break this into 5 steps instead of 3"

# Convert a linear workflow into an agentic long loop
$ comanda improve workflow.yaml "convert this to an agentic loop with prompt_improvement enabled"

# Add policy or context checks before the main task
$ comanda improve workflow.yaml "check POLICY.md before the analysis step"
          

The improve command uses your configured generation model, can be overridden with --model, and understands the same DSL guide used by comanda generate.

📺 Live TUI Dashboard#

Watch your workflows run in real time with a rich terminal UI. See iteration progress, token usage estimation, elapsed time, resource consumption, and the full story behind a long-running loop.

$ comanda process workflow.yaml --live

╭──────────────────────────────────────────────────╮
│  ✓ analyze_codebase                              │
│  Model: claude-code-sonnet                       │
│  Iteration 3/10 | Time: 45s | Context (est.): 12%│
╰──────────────────────────────────────────────────╯

Status: Running...
CPU: 12% | Memory: 128MB

[Press 'q' to quit | 'd' toggle debug | Ctrl+R full activity]
          

Inspect the complete activity history: Press Ctrl+R to open a full-screen, scrollable Recent Activity view. It retains up to 500 events and wraps complete error output instead of truncating it to the dashboard width. Press d to show the debug panel when running with --debug or --verbose.

Reliable long loops: Claude Code prompts are streamed through stdin, so large codebase indexes and iterative prompts do not hit the operating system's command-line length limit.

🌿 Git Worktree Support#

Run multiple Claude Code sessions in parallel on the same repo without conflicts. Comanda automatically manages Git worktrees so each agent gets an isolated working copy.

Terminal

# Run two agentic tasks in parallel—no conflicts!
$ comanda process parallel-features.yaml --live

# Each agent works in its own worktree
# Changes are merged back when complete
          

⚡ Parallel Processing#

Run independent steps concurrently for faster workflows. Automatically waits for all parallel steps before continuing.

model-comparison.yaml

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
          

🎯 Intelligent Flow Control#

Let the LLM decide when work is complete, route dynamically based on content, and handle failures gracefully.

LLM-Decides Exit

Agentic loops continue until the model says "DONE" — no fixed iteration counts.

Conditional Steps

Skip steps based on previous outputs or environment variables.

Quality Gates

Validate outputs before proceeding. Retry on failure with backoff.

Explicit Data Flow

Chain steps through STDIN/STDOUT or explicit output files.

intelligent-pipeline.yaml

prepare:
  input: STDIN
  model: gpt-5.6-terra
  action: "Turn this request into an implementation plan with acceptance criteria."
  output: ./plan.md

implement:
  input: ./plan.md
  model: claude-code
  agentic_loop:
    exit_condition: llm_decides
    max_iterations: 10
  action: "Implement the plan. Run tests. Say DONE when all criteria pass."
  output: STDOUT
          

🛠️ Tool Execution#

Run shell commands, scripts, and CLIs within your workflows. Integrate with grep, jq, git, or any command-line tool.

git-workflow.yaml

get-diff:
  tool: bash
  input: "git diff HEAD~1"
  output: ./diff.txt

review:
  input: ./diff.txt
  model: claude-code
  action: "Review these changes for issues"
  output: STDOUT
          

📊 Workflow Visualization#

See the structure of any workflow at a glance. Understand parallel branches, sequential steps, and data flow.

$ comanda chart workflow.yaml

╔════════════════════════════════════════════════╗
║      WORKFLOW: agentic-explore.yaml            ║
╚════════════════════════════════════════════════╝

┌────────────────────────────────────────────────┐
│              INPUT: None required              │
└────────────────────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────┐
│  ✓ explore_codebase                            │
├────────────────────────────────────────────────┤
│  Model: claude-code-sonnet                     │
│  Explore this codebase and provide             │
└────────────────────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────┐
│                 OUTPUT: STDOUT                 │
└────────────────────────────────────────────────┘

╔════════════════════════════════════════════════╗
║ STATISTICS                                     ║
├────────────────────────────────────────────────┤
│  Steps: 1 total, 0 parallel                    │
│  Valid: 1/1                                    │
╚════════════════════════════════════════════════╝
          

🌐 Multi-Provider Support#

Connect to any LLM provider. Cloud APIs, local models via Ollama, enterprise deployments via AWS Bedrock, or agentic coding tools—all in the same workflow.

Category	Provider	Models	Config
Cloud APIs	Anthropic	Claude 4.5 (Opus, Sonnet, Haiku), Claude 4, 3.7, 3.5	`ANTHROPIC_API_KEY`
	OpenAI	GPT-5.6 (Sol, Terra, Luna), GPT-5, GPT-4o, o3, o4-mini	`OPENAI_API_KEY`
	Google	Gemini 3, 2.5 (Pro, Flash), 1.5	`GOOGLE_API_KEY`
	X.AI	Grok 4.5, Grok 4.3, Grok 4, Grok Vision	`XAI_API_KEY`
	DeepSeek	DeepSeek-Chat, Coder, Vision, Reasoner	`DEEPSEEK_API_KEY`
	Moonshot	Moonshot v1 (8k, 32k, 128k)	`MOONSHOT_API_KEY`
	Sakana	Fugu, Fugu Ultra	`SAKANA_API_KEY`
Enterprise	AWS Bedrock	Claude, Nova, Llama via Converse API	AWS credentials
Local / Self-hosted	Ollama	Any model (Llama, Mistral, Qwen, etc.)	Auto-detected
Local / Self-hosted	vLLM	Any OpenAI-compatible endpoint	`VLLM_ENDPOINT`
Agentic Tools	Claude Code	`claude-code`, `claude-code-opus`	CLI installed
	OpenAI Codex	`openai-codex`, `openai-codex-o3`	CLI installed
	Gemini CLI	`gemini-cli`, `gemini-cli-pro`	CLI installed
	Kimi Code	`kimi-code`, `kimi-code-<alias>`	`kimi` CLI installed

Inspect your configured model surface

# In the interactive Models & Providers submenu
$ comanda configure

# Choose: Models & Providers → List Models & Providers
Configured providers, model aliases, targets, and your default model
          

Using AWS Bedrock

# Bedrock models use the bedrock/ prefix
analyze:
  model: bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0
  action: "Analyze this architecture"
  input: STDIN
  output: STDOUT

# AWS credentials from environment, ~/.aws/credentials, or IAM role
# Set AWS_REGION (defaults to us-east-1)
          

📁 Advanced I/O#

Process files, URLs, databases, and images. Batch operations with wildcards. Automatic chunking for large files.

Input Type	Formats	Features
Files	Any text file, wildcards (`.go`, `src//.ts`)	Multi-file input, auto-chunking for large files, file watching
Documents	PDF, Markdown, plain text	Page extraction, table parsing, inline images
Images	PNG, JPEG, GIF, WebP	Vision model analysis, screenshots, base64 encoding
URLs	HTTP/HTTPS web pages	Content extraction, screenshots, headless rendering
Databases	PostgreSQL	Query execution, result streaming, schema introspection
Streams	STDIN, pipes	Unix pipeline integration, streaming output

batch-process.yaml

# Process all Go files in a directory
review-code:
  input: ./src/**/*.go
  model: claude-code
  action: "Review each file for security issues"
  output: security-report.md

# Analyze a webpage screenshot
analyze-ui:
  input: url:https://example.com
  model: gpt-5.6-terra
  action: "Analyze this UI for accessibility issues"
  output: STDOUT
          

📚 Codebase Indexing#

Generate agent-ready repository context—not merely a file tree. A structured index captures architecture, local conventions, evidence, confidence, and the reasoning future agents need before they make changes.

Terminal

# Index and register a codebase with deeper architecture analysis
$ comanda index capture ~/my-project -n myproject --enhance --max-files 10000

# List all registered indexes
$ comanda index list
NAME         PATH              LAST INDEXED         FORMAT       FILES
myproject    ~/my-project      2024-02-25 15:00     structured   142

# Incremental update — only re-index changed files
$ comanda index update myproject --max-files 10000
Scanning for changes... 3 files modified
Updated in 0.3s (vs 2.1s full)

# Check what changed since last index
$ comanda index diff myproject
          

Built for real repositories: capture considers up to 10,000 source files by default; set max_files: 0 in a workflow or pass --max-files 0 for no source-file cap. The optional --enhance pass adds macro architecture guidance, while deterministic analysis mines repeated repository patterns into evidence-backed editing advice.

multi-codebase-analysis.yaml

# Load indexes from registry
load_context:
  codebase_index:
    use: [project1, project2]
    aggregate: true

compare:
  input: |
    Compare these codebases:
    ${INDEX:project1}
    ${INDEX:project2}
  model: claude-code
  action: "Identify shared patterns and differences"
  output: comparison.md
          

TurboQuant compression: Indexes are automatically compressed using vector quantization and chunk deduplication, reducing size by up to 50% while preserving semantic quality. The comanda generate command also auto-detects available indexes in .comanda/ and includes them in the prompt context.

Building Rich Context with Agentic Loops

Combine indexing with agentic exploration to build deep, searchable knowledge bases. The agent explores the codebase iteratively, writing findings to a local search index (like qmd) for later retrieval.

build-knowledge-base.yaml

# Step 1: Create a rich, persistent index of the codebase
index:
  tool: bash
  input: "comanda index capture ./src -n myproject --enhance --max-files 10000"
  output: STDOUT

# Step 2: Let the agent inspect the index selectively, then write durable docs
explore:
  input: .comanda/myproject_INDEX.md
  model: claude-code
  allowed_paths: [., ./src, ./docs]
  agentic_loop:
    exit_condition: llm_decides
    max_iterations: 50
  action: |
    Use the index as a map, then read only the relevant source files.
    Document architecture, conventions, important modules, and pitfalls in ./docs/.
    Do not echo index contents; return a concise status. Say DONE when complete.
  output: STDOUT

# Step 3: Index the generated docs for semantic search
build-search-index:
  tool: bash
  input: "qmd index ./docs --name project-knowledge"
  output: STDOUT
          

Now you can query your knowledge base: qmd search "how does auth work" — and get semantically relevant results from the agent's exploration. Great for onboarding, code review prep, or building RAG context for future workflows.

🧩 Skills System#

Define reusable, parameterized workflows as Markdown files with YAML frontmatter. Skills are Claude-compatible, discoverable, and can be invoked from the CLI or within other workflows.

~/.comanda/skills/summarize.md

---
description: "Summarize a document or code file"
arguments:
  file:
    description: "Path to file to summarize"
    required: true
  format:
    description: "Output format (bullets, prose, tldr)"
    default: "bullets"
allowed-tools: [Read]
---

Read ${file} and summarize it in ${format} format.
Focus on key points, decisions, and action items.
          

Terminal

# List available skills
$ comanda skills list
SKILL        DESCRIPTION                           SOURCE
summarize    Summarize a document or code file     ~/.comanda/skills/
code-review  Review code for issues                bundled

# Run a skill directly
$ comanda skills run summarize --file README.md --format tldr

# Use in a workflow step
summarize-docs:
  skill: summarize
  skill_args:
    file: ./docs/API.md
    format: prose
  output: STDOUT
          

Skill locations: User skills in ~/.comanda/skills/, project skills in .comanda/skills/, plus bundled skills included with comanda. Skills support ${VAR} and ${VAR:-default} substitution.

🛡️ Security Scanning#

Scan dependencies for known vulnerabilities using real-time data from OSV.dev. Works with npm, PyPI, Go, Cargo, and more.

examples/security/zeroday-scanner.yaml

parse-deps:
  input: STDIN
  model: grok-4-1-fast-non-reasoning
  action: "Extract dependencies as JSON array"
  output: ./deps.json

query-osv:
  input: ./deps.json
  model: NA
  tool_config:
    allowlist: [curl, jq]
  action: NA
  output: "tool: jq ... | curl api.osv.dev/v1/query ..."

generate-report:
  input: ./vulns.json
  model: grok-4-1-fast-non-reasoning
  action: "Generate security report with CVEs and remediation"
  output: STDOUT
          

$ cat package.json | comanda process zeroday-scanner.yaml

🔴 CRITICAL minimist@1.2.5
   GHSA-xvch-5gv4-984h — Prototype Pollution
   Fixed: 1.2.6
   Run: npm install minimist@1.2.6

🟠 HIGH lodash@4.17.20
   GHSA-35jh-r3h4-6jhm — Command Injection
   Fixed: 4.17.21
   Run: npm install lodash@4.17.21

✅ 4 packages scanned, 2 vulnerabilities found
          

Real-time data: Queries OSV.dev API directly—no stale vulnerability databases. Uses tool_config.allowlist to enable curl for API access. Works in CI/CD pipelines.

🚀 Server Mode#

Turn any workflow into an HTTP API. Perfect for integrating comanda into your existing services and CI/CD pipelines.

Terminal

# Start the server
$ comanda server

# Call any workflow via HTTP
$ curl -X POST "http://localhost:8080/process?filename=review.yaml" \
    -d '{"input": "code to review"}'
          