GitHub - Shopify/roast: Structured AI workflows made easy

A Ruby-based domain-specific language for creating structured AI workflows. Build complex AI-powered automation with simple, declarative Ruby syntax.

Overview

Roast lets you orchestrate AI workflows by combining "cogs" - building blocks that interact with LLMs, run code, execute commands, and process data. Write workflows that:

• Chain AI steps together - Output from one cog flows seamlessly to the next
• Run coding agents locally - Full filesystem access with Pi, Claude Code, or other providers
• Process collections - Map operations over arrays with serial or parallel execution
• Control flow intelligently - Conditional execution, iteration, and error handling
• Reuse workflow components - Create modular, parameterized scopes

Quick Example

# analyze_codebase.rb
execute do
  # Get recent changes
  cmd(:recent_changes) { "git diff --name-only HEAD~5..HEAD" }

  # AI agent analyzes the code
  agent(:review) do
    files = cmd!(:recent_changes).lines
    <<~PROMPT
      Review these recently changed files for potential issues:
      #{files.join("\n")}

      Focus on security, performance, and maintainability.
    PROMPT
  end

  # Summarize for stakeholders
  chat(:summary) do
    "Summarize this for non-technical stakeholders:\n\n#{agent!(:review).response}"
  end
end

Run with:

bin/roast execute analyze_codebase.rb

Core Cogs

• chat - Send prompts to cloud-based LLMs (OpenAI, Anthropic, Perplexity & Gemini)
• agent - Run local coding agents with filesystem access (Pi CLI, Claude Code CLI, etc.)
• ruby - Execute custom Ruby code within workflows
• cmd - Run shell commands and capture output
• map - Process collections in serial or parallel
• repeat - Iterate until conditions are met
• call - Invoke reusable workflow scopes

Installation

Or add to your Gemfile:

Requirements

• Ruby 3.0+
• API keys or local credentials for your AI provider
• Pi CLI installed (for the default agent provider)

Provider Configuration

Roast provider settings are configured in workflow config blocks. To change the default chat provider without editing each workflow, set the ROAST_DEFAULT_CHAT_PROVIDER environment variable (e.g. export ROAST_DEFAULT_CHAT_PROVIDER=anthropic). To change the default agent provider, set ROAST_DEFAULT_AGENT_PROVIDER. A provider set in a workflow's config always takes precedence over these variables, and an invalid value raises an error.

Chat cog

The chat cog supports OpenAI, Anthropic, Perplexity, and Gemini. It defaults to :openai (override globally with ROAST_DEFAULT_CHAT_PROVIDER). Each provider reads its API key from a provider-specific environment variable:

You can configure the provider directly in a workflow:

config do
  chat do
    provider :anthropic
    model "claude-haiku-4-5"
  end
end

Agent cog

The agent cog runs local agent CLIs. It defaults to :pi (override globally with ROAST_DEFAULT_AGENT_PROVIDER) and currently supports:

• :claude - Claude Code CLI
• :pi - Pi CLI

Select a provider in the workflow config:

config do
  agent do
    provider :pi
  end
end

Agent providers must be installed and authenticated according to their own CLI requirements.

Configuration

Roast currently supports four LLM providers for the chat cog: OpenAI, Anthropic, Perplexity and Gemini.

• Set OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY and/or GEMINI_API_KEY in your environment.
• Optionally set OPENAI_API_BASE, ANTHROPIC_API_BASE and/or GEMINI_API_BASE to override the default endpoint. Perplexity does not support base URL override.

The default model is set per-provider and can only be overridden inside a config block. See the tutorial for examples.

The agent cog is powered by the Pi CLI by default, which handles its own authentication.

Getting Started

The best way to learn Roast is through the interactive tutorial:

📚 Start the Tutorial

The tutorial covers:

1. Your first workflow
2. Chaining cogs together
3. Accepting targets and parameters
4. Configuration options
5. Control flow
6. Reusable scopes
7. Processing collections
8. Iterative workflows
9. Async execution

Documentation

• Tutorial - Step-by-step guide with examples
• Workflow Examples - Toy workflows that demonstrate all functional patterns, use for end-to-end test

Documentation & References

• Source code root: https://github.com/Shopify/roast/tree/main/lib/roast

The public interfaces of Roast are extensively documented in class and method comments on the relevant classes.

• Tutorial and Examples
  • Tutorial -- Table of Contents (contains step-by-step guides and runnable examples showing real-world usage)
  • Additional Example Workflows (these comprise the Roast end-to-end test suite)
• Configuation
  • General configuration block: config-context.rbi
  • Workflow params in cog config blocks: cog/config.rbi
  • Global cog configuration: cog/config.rb
  • Agent cog configuration: agent/config.rb
  • Chat cog configuration: chat/config.rb
  • Cmd cog configuration: cmd/config.rb
  • Map cog configuration: map.rb
• Execution
  • General Execution block: execution-context.rbi
• Input and Output
  • General cog input block: cog-input-context.rbi
  • Global cog output: cog/output.rb
  • Agent cog input agent/input.rb
  • Agent cog output agent/output.rb
  • Call cog input: call.rb
  • Chat cog input: chat.rb
  • Chat cog output: chat.rb
  • Cmd cog input: cmd.rb:159 (scroll down)
  • Cmd cog output: cmd.rb:214 (scroll down)
  • Map cog input: map.rb:116 (scroll down)
  • Repeat cog input: repeat.rb
  • Ruby cog input: ruby.rb
  • Ruby cog output: ruby.rb:63 (scroll down)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License