Shopify Roast

Executive Summary

Shopify Roast is an open-source Ruby gem for creating structured AI workflows. Rather than building a full coding agent, Roast provides orchestration primitives ("cogs") that chain LLM calls, shell commands, coding agents, and custom Ruby together. The philosophy: non-determinism is the enemy of reliability — structure keeps agents on track. Now at v1.0 preview with an active community.

Attribute	Value
Company	Shopify
Type	Open-source Ruby gem
License	MIT
Version	1.0 preview
Install	gem install roast-ai

---

Product Overview

Roast lets developers orchestrate AI workflows by combining "cogs" — building blocks that interact with LLMs, run code, execute commands, and process data. The key insight is that AI should only be invoked for parts of problems it's best suited for, within a deterministic structure.

Core Cogs

Cog	Description	Example
chat	Cloud LLM calls (OpenAI, Anthropic, Gemini)	Summarization, analysis
agent	Local coding agents with filesystem access	Claude Code CLI integration
ruby	Custom Ruby code execution	Business logic, transformations
cmd	Shell commands with output capture	Git operations, linting
map	Collection processing (serial/parallel)	Batch operations
repeat	Iteration until conditions met	Convergence loops
call	Reusable workflow invocation	Modular composition

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

---

Technical Architecture

Roast builds on Raix, Shopify's Ruby library for AI components (similar to AI SDK for JavaScript).

Workflow Structure

execute do
  ├── Deterministic cogs (cmd, ruby)
  ├── AI cogs (chat, agent)
  ├── Control flow (map, repeat)
  └── Composition (call)
end
    ↓
Outputs flow between cogs
    ↓
Structured, predictable result

Configuration

Aspect	Options
Chat providers	OpenAI, Anthropic, Gemini
Agent backend	Claude Code CLI
Execution	Serial or parallel (map cog)
Output formats	Per-cog configuration

Key Technical Details

Aspect	Detail
Language	Ruby 3.0+
Dependencies	Raix (AI components), Claude Code CLI (for agent cog)
Workflow syntax	Ruby DSL (v1.0); YAML deprecated (v0.x)
Parallelism	Configurable via map cog
State	Output from one cog flows to next

---

Strengths

• Open source — MIT-licensed Ruby gem freely available; full source code on GitHub
• Multi-agent orchestration — Chain LLM calls, coding agents, shell commands, custom Ruby in single workflow
• Serial and parallel execution — Map operations with configurable parallelism
• Composable — Modular scopes with parameters enable workflow reuse
• Claude Code integration — agent cog runs Claude Code CLI with full filesystem access
• Deterministic structure — AI invoked only where needed, within predictable framework

---

Cautions

• Ruby-specific — Ecosystem limited to Ruby shops; no Python/JavaScript equivalents
• Requires Claude Code — agent cog depends on external CLI installation
• Workflow complexity — DSL learning curve for non-trivial pipelines
• v1.0 transition — Breaking changes from v0.x YAML syntax; migration required
• Not a full agent — Orchestration primitives, not autonomous agent with reasoning

---

Competitive Positioning

vs. Other Approaches

System	Differentiation
Stripe Minions	Minions are autonomous agents; Roast is workflow orchestration
LangChain	Roast is Ruby-native; LangChain is Python/JS
Temporal	Roast is AI-focused; Temporal is general workflow
Agent frameworks	Roast structures agents; doesn't replace them

When to Use Roast

• Use Roast when: You need structured AI workflows mixing deterministic and LLM steps
• Use full agents when: You need autonomous reasoning over complex problems
• Use LangChain when: Your team is Python/JavaScript, not Ruby

---

Ideal Customer Profile

Good fit:

• Ruby-on-Rails shops (Shopify, Basecamp ecosystem)
• Teams wanting structured AI workflows, not autonomous agents
• Workflows mixing shell commands, APIs, and LLM calls
• Need for reproducible, testable AI pipelines

Poor fit:

• Python/JavaScript teams (no direct equivalent)
• Need for fully autonomous agent reasoning
• Simple single-LLM-call use cases (overkill)
• No existing Claude Code setup

---

Installation & Usage

gem install roast-ai

Or in Gemfile:

gem 'roast-ai'

Requirements:

• Ruby 3.0+
• API keys for AI provider (OpenAI/Anthropic)
• Claude Code CLI installed (for agent cog)

---

Viability Assessment

Factor	Assessment
Open Source Health	Strong (Shopify backing, active development)
Documentation	Good (tutorial, examples, API docs)
Community	Growing (GitHub activity)
Production Use	Yes (Shopify internal + external adopters)
Long-term Outlook	Positive (v1.0 shows commitment)

Roast represents Shopify's investment in AI workflow tooling. The progression from v0.x YAML to v1.0 Ruby DSL shows active development and response to user feedback.

---

Bottom Line

Shopify Roast is the reference implementation for structured AI workflows in Ruby. The key philosophy — non-determinism is the enemy of reliability — positions Roast as orchestration layer, not replacement for agents.

Key insight: AI should be invoked only for parts of problems it's best suited for, within deterministic structure.

Use for: Multi-step AI workflows mixing LLM calls, shell commands, and coding agents.

Don't use for: Autonomous agent reasoning, non-Ruby stacks, simple single-call use cases.

Recommended for: Ruby teams building AI automation, Shopify ecosystem developers, engineers wanting structured approach to AI workflows.

Not recommended for: Python/JS teams, organizations needing fully autonomous agents.

Outlook: Roast fills a gap in the Ruby AI ecosystem. Expect growing adoption among Rails shops as AI workflow automation becomes standard practice.

---

Research by Ry Walker Research • methodology

Disclosure: Author is CEO of Tembo, which offers agent orchestration as an alternative to building in-house.