Minion Engine

Automate code review, bug fixing, and PR creation with AI — defined in YAML, executed in Docker.

Minion Engine is a CLI tool that runs multi-step AI workflows. You define what you want in a YAML file, and it orchestrates everything: shell commands, Claude AI calls, conditional logic, and parallel execution — all inside an isolated Docker sandbox.

You write YAML → Minion runs AI workflows → Results appear as PR comments, fixes, reports

Why?

Without Minion Engine, reviewing a PR means:

• Open the PR, read each file manually
• Switch context between Python, TypeScript, Rust conventions
• Remember to check for security issues, type safety, error handling
• Write your findings as a comment

With Minion Engine, one command does it all:

minion execute code-review.yaml -- 42

Every changed file is reviewed with language-specific criteria (Python gets Python rules, TypeScript gets TypeScript rules), the project architecture is considered, and a structured report is posted as a PR comment.

Typical execution times:

Execution time depends on several factors:

• Docker sandbox setup (1–5 min on first run per session): creating the container, copying your project files in, and initializing git. Larger projects with more files take longer to copy.
• API response time (10–60s per call): each chat or agent step makes a round-trip to the Claude API. Longer prompts and larger context windows increase latency.
• Retry loops: workflows like fix-issue run lint and test gates in a repeat scope — if tests fail, the agent fixes and retries (up to max_iterations). Each iteration adds a full agent + cmd cycle.
• Parallelism vs rate limits: map steps with parallel: 5 can trigger API rate limits (429), which currently causes failures. Lower parallelism is more reliable.
• First run: the Docker image build (minion-sandbox:latest) adds ~2 minutes the very first time. Subsequent runs use the cached image.

Quick Start

# 1. Install (Rust toolchain required)
cargo install minion-engine

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

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

# 4. Go to your project and run a workflow
cd /path/to/your-project
minion execute code-review.yaml -- 42   # Review PR #42

That's it. Docker image is built automatically on first run. No manual setup needed.

What Can It Do?

All workflows are YAML files you can customize or create from scratch.

Prerequisites

Docker image auto-build: The first time you run a workflow, Minion automatically builds the sandbox image (minion-sandbox:latest). This takes ~2 minutes once and never needs to be repeated.

Features

🐳 Docker Sandbox (default)

Every workflow runs inside an isolated Docker container. Your project is copied in, the AI works in isolation, and only the results come back. If anything goes wrong, the container is destroyed — zero impact on your project.

minion execute code-review.yaml -- 42        # Sandbox ON (default)
minion execute code-review.yaml --no-sandbox -- 42  # Run locally instead

🔍 Language-Aware Code Review

The code review workflow detects the language of each changed file and applies language-specific review criteria:

• Python → checks for bare except:, missing type annotations, mutable default arguments
• TypeScript → checks for any types, missing await, unhandled promise rejections
• Rust → checks for unwrap() in production, unnecessary clones, unsafe blocks
• Java → checks for resource leaks, null safety, checked exceptions
• Falls back to generic review for other languages

📐 Architecture Context

If your project has a CLAUDE.md, ARCHITECTURE.md, or README.md, the code review workflow reads it automatically and uses it to evaluate whether changes align with your project's design.

🎯 Stack Detection & Prompt Registry

Minion detects your project's tech stack (Rust, Python, TypeScript, React, Java, etc.) from file markers (Cargo.toml, package.json, requirements.txt) and uses it to select the right prompts and tools.

CLI Reference

minion execute

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

# Examples
minion execute code-review.yaml -- 42              # Review PR #42
minion execute fix-issue.yaml --verbose -- 247     # Fix issue with verbose output
minion execute fix-test.yaml -- 7                  # Fix failing tests for PR #7
minion execute security-audit.yaml                 # Security audit (no target needed)
minion execute workflow.yaml --var mode=strict -- 5 # Pass variables

minion init

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

Creates a new workflow from a built-in template.

Templates: blank, fix-issue, code-review, security-audit

minion validate

minion validate <workflow.yaml>

Parses and validates a workflow without executing it.

minion list

minion list

Lists workflows found in the current directory, ./workflows/, and ~/.minion/workflows/.

minion inspect

minion inspect <workflow.yaml>

Shows config layers, scopes, step dependency graph, and dry-run summary.

Workflow YAML Format

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

config:
  global:
    timeout: 300s
  chat:
    provider: anthropic
    model: claude-sonnet-4-20250514
    api_key_env: ANTHROPIC_API_KEY
  cmd:
    fail_on_error: true

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

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

  - name: report
    type: cmd
    run: "echo 'Analysis complete'"

Step Types

Template Variables

Example Output

▶ code-review
  🔒 Sandbox mode: FullWorkflow
  🐳 Creating Docker sandbox container…
  🔒 Sandbox ready — container 1.3s, copy 12.4s, git 98.7s (total 112.4s)
  ✓ get_diff (3.2s)
  ✓ changed_files (1.8s)
  ✓ check_files (0.0s)
  ✓ file_reviews (45.3s)    ← map scope: reviews each file with language-specific criteria
  ✓ summary (28.1s)          ← chat step: synthesizes all reviews into a report
  ✓ post_comment (2.1s)
  ✓ report (0.3s)
  📦 Copying results from sandbox…
  🗑️  Sandbox destroyed

✓ Done — 7 steps in 193.2s

Project Structure

src/
  cli/          # CLI commands (execute, validate, list, init, inspect)
  engine/       # Core engine — step execution, context, templates
  workflow/     # YAML parsing, validation
  steps/        # Step executors (cmd, agent, chat, gate, repeat, map, parallel)
  sandbox/      # Docker sandbox management
  prompts/      # Stack detection and prompt registry
  config/       # 4-layer config resolution
  plugins/      # Dynamic plugin system
workflows/      # Example workflow YAML files
prompts/        # Language-specific prompt templates

License

MIT