Build AI features that feel at home in Ruby

LittleGhost is a Ruby library for adding AI features to an existing application or building a dedicated AI service. An agent combines a model with instructions and Ruby operations it can call. Agents can work together in an assembly, which your application calls like a single agent.

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.

With the gem installed and OPENROUTER_API_KEY set, start with one class:

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. The decision example shows typed questions with Jev through OpenRouter.

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. For operations that need files or child processes, see Workspaces and Sandboxes.

Grow without changing the caller

When a task needs several agents, choose how they work together. These example classes use different coordination styles, but their callers all use .ask:

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 is a specialist an agent can ask for help.
• 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.

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 and choose which participants to display. Getting Started shows how to stream an Agent's answer and read the completed result.

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

This is the beginning of the README. Read the rest at the original. Read the full README ↗