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. ^[1] The Ruby-DSL rewrite shipped as v1.0.0 in February 2026, and v1.1.0 (April 2026) added the Pi coding agent as a second agent backend alongside Claude Code. The repo sits at ~1.2K stars with active commits as of June 2026. ^{[2] [3]}

---

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

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, an open-source Ruby library for AI components maintained under the OlympiaAI organization — not a Shopify repository, despite Roast's dependence on it. ^[4]

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

Key Technical Details

---

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
• Coding agent integration — agent cog runs Claude Code (or Pi, since v1.1.0) with full filesystem access, multiple prompts per session, and usage tracking ^[2]
• Deterministic structure — AI invoked only where needed, within predictable framework

---

Cautions

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

---

Competitive Positioning

vs. Other Approaches

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 or Pi installed (for agent cog)

---

What Developers Say

Practitioner commentary is positive but thin — multiple Hacker News submissions of Roast drew almost no discussion (none above a handful of points, with at most two comments), so the signal comes from individual engineering blogs rather than forum threads.

Dion Almaer, writing at tessl.io, on why the framework matters:

"Roast unlocks safe collaboration between humans and AI at scale, with a clear 'why' rooted in reclaiming control and traceability in LLM-driven development." ^[5]

Daniel Doubrovkine (code.dblock.org) walked through building a test-grading workflow and comparing model outputs with Roast, landing on a two-word verdict:

"Honestly, wow." ^[6]

Both writeups predate the v1.0 Ruby DSL; no substantive public practitioner reviews of the v1.x DSL era surfaced as of June 2026.

---

Viability Assessment

Roast represents Shopify's investment in AI workflow tooling. The progression from v0.x YAML to the v1.x Ruby DSL — and the addition of a second agent backend (Pi) within two months of v1.0 — 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 and is shipping at a steady clip — three v1.x releases between February and April 2026, including a second agent backend. Expect growing adoption among Rails shops as AI workflow automation becomes standard practice. ^[2]

---

Research by Ry Walker Research • methodology

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