Roast

🔥 version 1.0 feature preview 🔥

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

⚠️ Deprecation announcement ⚠️

The YAML-based workflow syntax of Roast v0.x will be removed in v1.0. All v0.x functionality is still supported during the feature preview. For the existing documentation for Roast v0.x , see README_LEGACY.md

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 --executor=dsl analyze_codebase.rb

Core Cogs

• chat - Send prompts to cloud-based LLMs (OpenAI, Anthropic, Gemini, etc.)
• 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)
• Claude Code CLI installed (for agent cog)

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
• Functional Tests - Toy workflows that demonstrate all functional patterns, use for end-to-end test
• API Reference - Complete cog documentation

Documentation & References

⚠️ Roast stills supports the legacy version 0.x. Examples of workflows using the new version 1.0-preview system are namespaced within the dsl hierarchy.

• v1.0 source code root: https://github.com/Shopify/roast/tree/main/lib/roast/dsl

The public interfaces of the new 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