Build AI features that feel at home in Ruby

Using a coding agent? Start with llms.txt for a concise map of the guides and API. llms-full.txt contains the complete documentation in one file.

LittleGhost is a Ruby library for building AI features with agents and composable assemblies. With OPENROUTER_API_KEY set, start with one class, give it a prompt, and call it like the rest of your application code:

require "little_ghost"

class CustomerSupportAgent < LittleGhost::Agent
  model "openrouter:openai/gpt-5.6-luna"
  system_prompt "Answer customer questions clearly and concisely."
end

run = CustomerSupportAgent.ask("Draft a friendly greeting for a customer.")
run.response
# One possible response: Hi! How can I help today?

That definition is a complete Agent. LittleGhost makes the model call, tracks usage, supports streaming, and closes request resources. Add a Tool for application capabilities or an Assembly as the work grows.

Model requests may send system instructions, caller input, conversation history, Tool results, and attachments to the selected provider. Model wording can vary between runs. Models and Providers explains how to choose where each Agent sends its requests.

Install the gem

LittleGhost requires Ruby 3.3 or newer. Add it to your bundle and provide a provider credential:

gem "little_ghost"

$ bundle install
$ export OPENROUTER_API_KEY="..."

The introductory guides use OpenRouter so you can start with one key. Prefer another hosted provider or a local Ollama or LM Studio server? See Provider Support.

LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI, or service.

Generate a small application

Generate a conventional standalone application:

$ gem install little_ghost
$ little_ghost new MyApp
$ cd my_app
$ export OPENROUTER_API_KEY="..."
$ bin/little_ghost console

The generator installs the bundle. bin/little_ghost console runs that bundle's LittleGhost version and loads the application before starting IRB.

The source checkout also includes a complete single-file Agent and coding harness, both configured for local Ollama.

Give an agent real capabilities

Tools let an agent call focused parts of your application:

class HelpCenterLookupTool < LittleGhost::Tool
  description "Look up a help center entry by topic."
  input_schema(
    type: "object",
    properties: {topic: {type: "string"}},
    required: ["topic"],
    additionalProperties: false
  )

  def call(input)
    {"refunds" => "Refunds are available within 30 days."}
      .fetch(input.fetch("topic"), "No help center entry found.")
  end
end

class CustomerSupportAgent < LittleGhost::Agent
  model "openrouter:openai/gpt-5.6-luna"
  system_prompt "Check the help center before stating company guidance."
  tools HelpCenterLookupTool
end

The schema checks the shape of the input. Your Ruby code still decides whether the operation is allowed. The result goes back to the model as context.

An ordinary Tool runs in your Ruby process. When a Tool needs files or child processes, it can delegate that work through a Sandbox. Code mode goes one step further: a sandboxed interpreter can compose several Tools, while every Tool call still returns to your Ruby Tool for validation and permission checks.

Grow without changing the caller

An agent owns one model loop. An assembly is one or more agents working as a unit. You call either one the same way:

CustomerSupportAgent.ask(question)
ResponseWorkflow.ask(question)
ProblemSolverSwarm.ask(question)
SupportFlowGraph.ask(question)

Choose the coordination style that matches who should control the next step:

  • A subagent lets a model delegate an addressable task.
  • A workflow uses ordinary Ruby for ordering and branching.
  • A swarm lets configured agents choose permitted handoffs.
  • A graph makes allowed routes explicit as nodes and edges.

A Workflow or Graph can contain agents, other assemblies, or both. Named classes are the clearest place to begin. Builders are there when your application discovers the participants or routes at runtime.

request ──> CustomerSupportAgent

request ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent

request ──> ProblemSolverSwarm ──> TriageAgent ──handoff──> BillingAgent

request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseAgent

The result stays familiar too. Every call returns a Run with the response, outcome, usage, and any final error. A coordinated assembly also records which participants ran. Use .stream_ask to watch the work as it happens.

LittleGhost is pre-1.0. Pin the gem version and review release notes before upgrading, because interfaces may change between releases.

Keep going

  • Getting Started takes you from installation to a tool-backed, streaming agent.
  • Core Concepts builds the mental model from Agent to Assembly.
  • Models and Providers explains targets, shared roles, and per-request model selection.
  • Provider Support has copyable setup for hosted APIs and local model servers.
  • Prompts as Views gives growing instructions, shared pieces, and application values a natural home.
  • Tools explains how models call focused Ruby operations.
  • MCP connects agents to operations published through the Model Context Protocol.
  • Structured Results and Content covers checked result shapes, images, and documents.
  • Compose Agents walks through workflows, swarms, graphs, nesting, and builders.
  • Skills organizes reusable instructions and supporting resources.
  • Workspaces and Sandboxes gives files and child processes a deliberate place to run.
  • Code Mode lets a model compose Tools in sandboxed Ruby or optional JavaScript.
  • Integrations connects Run streams to AG-UI and OpenTelemetry.
  • Running in Production covers configuration, saved conversations, supervision, and observability.
  • API reference provides exact method signatures and ownership rules.

For contributors

See the contributing guide, Code of Conduct, and security policy.

$ bundle install
$ bundle exec rake test
$ bundle exec standardrb --no-fix

LittleGhost is available under the MIT License.