Roast

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 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 (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

gem install roast-ai

Or add to your Gemfile:

gem 'roast-ai'

Requirements

• Ruby 3.0+
• API keys for your AI provider (OpenAI, Anthropic, Perplexity & Gemini)
• Claude Code CLI installed (for agent cog)

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 Claude Code CLI, 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
  • 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