Minion Engine

AI workflow engine that orchestrates Claude Code CLI through declarative YAML workflows.

Overview

Minion Engine executes multi-step workflows that combine shell commands, Claude Code AI agent calls, conditional gates, and retry loops. It powers automated workflows like fixing GitHub issues end-to-end (fetch → plan → implement → lint → test → PR).

┌──────────────────────────────────────────────┐
│              minion execute                  │
│                                              │
│  YAML Workflow                               │
│  ┌─────────────────────────────────────┐    │
│  │  steps:                             │    │
│  │    cmd  → shell command             │    │
│  │    agent → Claude Code CLI          │    │
│  │    gate  → conditional branch       │    │
│  │    repeat → retry loop              │    │
│  │    map   → iterate over items       │    │
│  │    parallel → concurrent steps      │    │
│  │    call  → invoke a scope           │    │
│  │    template → render prompt file    │    │
│  └─────────────────────────────────────┘    │
│                                              │
│  Context Store: step outputs, variables      │
│  Template Engine: Tera ({{ expressions }})   │
│  Config: 4-layer merge (global/type/pattern/step) │
└──────────────────────────────────────────────┘

Prerequisites

• Rust 1.75+ (rustup recommended)
• claude CLI installed and authenticated (for agent steps)
• gh CLI authenticated (gh auth login) — GH_TOKEN is auto-detected, no need to export it manually
• ANTHROPIC_API_KEY environment variable set (for chat and map steps)
• Docker Desktop 4.40+ (sandbox is ON by default — required unless you use --no-sandbox)

Build

cargo build --release
# binary at: ./target/release/minion

Install

Via crates.io (recommended)

cargo install minion-engine
minion --version

Build from source

git clone https://github.com/allanbrunobr/minion-engine.git
cd minion-engine
cargo install --path .

Quick Start

# 1. Install
cargo install minion-engine

# 2. Set your Anthropic API key (once)
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Authenticate with GitHub (once) — GH_TOKEN is auto-detected
gh auth login

# 4. Run a code review on PR #42 (sandbox is ON by default)
minion execute workflows/code-review.yaml --sandbox -- 42

That's it. No manual GH_TOKEN export, no shell tricks — credentials are auto-detected.

# More examples
minion init my-workflow --template fix-issue     # Create from template
minion execute my-workflow.yaml --verbose -- 247  # Run with verbose output
minion execute my-workflow.yaml --no-sandbox -- 1 # Run without Docker sandbox
minion list                                       # List available workflows
minion inspect my-workflow.yaml                   # Show dependency graph
minion validate my-workflow.yaml                  # Validate without running

Usage

minion execute

minion execute <workflow.yaml> [flags] -- [target]

Flags:
  --no-sandbox      Disable Docker sandbox (sandbox is ON by default)
  --verbose         Show all step outputs
  --quiet           Only show errors
  --json            Output final result as JSON
  --var KEY=VALUE   Set a workflow variable (repeatable)
  --timeout N       Override global timeout in seconds

minion validate

minion validate <workflow.yaml>

Parses and validates the workflow without executing steps.

minion list

minion list

Lists workflows found in:

• Current directory
• ./workflows/
• ~/.minion/workflows/

Shows name, description, and step count for each.

minion init

minion init <name> [--template <template>] [--output <dir>]

Creates a new workflow YAML file from a built-in template.

Available templates: blank, fix-issue, code-review, security-audit

minion inspect

minion inspect <workflow.yaml>

Shows:

• Validation status
• Resolved config layers
• Scopes with step counts
• Step dependency graph
• Dry-run summary (step type breakdown)

Workflow YAML Format

name: my-workflow
version: 1
description: "What this workflow does"

config:
  global:
    timeout: 300s
  agent:
    model: claude-sonnet-4-20250514
    permissions: skip
  cmd:
    fail_on_error: true
  patterns:
    "^lint.*":
      fail_on_error: false

scopes:
  retry_loop:
    steps:
      - name: run_cmd
        type: cmd
        run: "npm test"
        config:
          fail_on_error: false
      - name: check
        type: gate
        condition: "{{ steps.run_cmd.exit_code == 0 }}"
        on_pass: break
    outputs: "{{ steps.run_cmd.stdout }}"

steps:
  - name: fetch_data
    type: cmd
    run: "gh issue view {{ target }} --json title,body"

  - name: analyze
    type: agent
    prompt: |
      Analyze this issue and suggest a fix:
      {{ steps.fetch_data.stdout }}

  - name: validate
    type: repeat
    scope: retry_loop
    max_iterations: 3

Step Types

See docs/STEP-TYPES.md for full documentation.

Template Variables

Example: Fix a GitHub Issue

# Sandbox is ON by default — AI runs isolated, your project stays safe
minion execute fix-issue --verbose -- 247

# Without sandbox (runs directly on your machine)
minion execute fix-issue --no-sandbox --verbose -- 247

This will:

1. Fetch the GitHub issue details
2. Find relevant source files
3. Plan the implementation (Claude agent)
4. Implement the fix (Claude agent)
5. Lint and auto-fix (repeat up to 3x)
6. Test and auto-fix (repeat up to 2x)
7. Create a branch, commit, push, and open a PR

All of this happens inside a Docker container by default. Your workspace is copied in, the AI works in isolation, and only the results are copied back. If anything goes wrong, the container is destroyed — zero impact on your project.

Docker Sandbox

The sandbox is ON by default — workflows run inside an isolated Docker container with auto-forwarded credentials.

# Build the sandbox image (once)
docker build -f Dockerfile.sandbox -t minion-sandbox:latest .

# Sandbox is ON by default — just run!
minion execute code-review -- 142
minion execute security-audit
minion execute weekly-report

# To run locally without sandbox:
minion execute code-review --no-sandbox -- 142

Three sandbox modes:

Credential auto-detection: ANTHROPIC_API_KEY is forwarded from your environment. GH_TOKEN is automatically detected from gh auth token if not explicitly set — no need to export it. Credential directories (~/.config/gh, ~/.ssh) are mounted read-only into the container.

Pre-flight validation: Before starting any workflow, minion checks that all required tools and credentials are available and gives clear, actionable error messages if anything is missing.

See docs/DOCKER-SANDBOX.md for full configuration.

Running Tests

cargo test

Project Structure

src/
  main.rs                  # Entry point
  lib.rs                   # Module re-exports
  cli/
    mod.rs                 # CLI subcommands (execute, validate, list, init, inspect, version)
    commands.rs            # Command implementations
    init_templates.rs      # Built-in workflow templates
    display.rs             # Terminal output helpers
  engine/
    mod.rs                 # Engine core — runs workflow steps
    context.rs             # Context store (step outputs, variables)
    template.rs            # Tera template rendering
  workflow/
    schema.rs              # WorkflowDef, StepDef, StepType
    parser.rs              # YAML → WorkflowDef
    validator.rs           # Validation rules
  steps/
    cmd.rs                 # Shell command executor
    agent.rs               # Claude Code CLI executor
    chat.rs                # Direct API chat executor
    gate.rs                # Conditional gate executor
    repeat.rs              # Retry loop executor
    map.rs                 # Map-over-items executor
    parallel.rs            # Parallel step executor
    call.rs                # Scope call executor
    template_step.rs       # Template rendering executor
  config/
    manager.rs             # 4-layer config resolution
    merge.rs               # YAML/JSON merge helpers
  control_flow.rs          # ControlFlow enum (skip, fail, break, next)
  error.rs                 # StepError enum
workflows/                 # Example workflow YAML files
tests/
  integration.rs           # Integration test suite
  fixtures/                # YAML test fixtures and mock scripts
docs/
  YAML-SPEC.md             # Complete YAML format specification
  STEP-TYPES.md            # Per-step-type documentation
  CONFIG.md                # 4-layer config system
  DOCKER-SANDBOX.md        # Running steps in Docker
  EXAMPLES.md              # Example workflow catalog

Documentation

• YAML Specification
• Step Types
• Configuration System
• Docker Sandbox
• Example Workflows

API Docs

cargo doc --open

License

MIT