An AI assistant for Ruby development. Works with IRB, Rails console, and the debug gem.

日本語版 README

• Context Awareness: Understands local variables, instance variables, and runtime state
• Tool Execution: AI autonomously executes code, inspects objects, and reads files
• Autonomous Investigation: AI loops through investigate-execute-analyze cycles
• Multi-environment Support: Works with IRB, Rails console, and debug gem (rdbg)
• Provider Agnostic: Use any LLM (OpenAI, Anthropic, Gemini, Ollama, etc.)

# 1. Install
gem install girb girb-ruby_llm

# 2. Set your API key
export GEMINI_API_KEY="your-api-key"  # or OPENAI_API_KEY, ANTHROPIC_API_KEY

# 3. Create ~/.girbrc
```ruby
require 'girb-ruby_llm'
Girb.configure do |c|
  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
end

girb

Then type a question and press **Ctrl+Space**, or use `qq <question>`.

## Table of Contents

1. [Configuration](#1-configuration) - Common setup for all environments
2. [Ruby Scripts (IRB)](#2-ruby-scripts-irb) - Using with pure Ruby
3. [Rails](#3-rails) - Using with Rails console
4. [Debug Gem (rdbg)](#4-debug-gem-rdbg) - Step-through debugging with AI

---

## 1. Configuration

### Installation

```bash
gem install girb girb-ruby_llm

Available provider gems:

• girb-ruby_llm - OpenAI, Anthropic, Gemini, Ollama, etc. (Recommended)
• girb-gemini - Google Gemini only (supports web search)

Set the API key for your chosen LLM provider as an environment variable:

export GEMINI_API_KEY="your-api-key"
# or OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

For detailed setup instructions (Ollama, other providers, advanced options), see the provider gem documentation:

• girb-ruby_llm
• girb-gemini

Create a .girbrc file in your project root (or home directory for global config):

# .girbrc
require 'girb-ruby_llm'

Girb.configure do |c|
  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
end

girb searches for .girbrc in this order:

1. Current directory → parent directories (up to root)
2. ~/.girbrc as fallback

# Google Gemini
c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')

# OpenAI
c.provider = Girb::Providers::RubyLlm.new(model: 'gpt-5.2-2025-12-11')

# Anthropic
c.provider = Girb::Providers::RubyLlm.new(model: 'claude-opus-4-5')

Girb.configure do |c|
  # Required: LLM provider
  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')

  # Optional: Debug output
  c.debug = true

  # Optional: Custom system prompt
  c.custom_prompt = <<~PROMPT
    This is production. Always confirm before destructive operations.
  PROMPT
end

Used when provider is not configured in .girbrc:

Persist AI conversation history across sessions. Only enabled when you explicitly set a session ID.

Set a session ID in .girbrc:

Girb.configure do |c|
  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
end

# Enable session persistence (optional)
Girb.debug_session = "my-project"

Or set dynamically in code:

Girb.debug_session = "debug-user-auth"
debugger  # Conversations in this session will be saved

Use in IRB or debug mode:

qq session status  # Show current session status
qq session list    # List saved sessions
qq session clear   # Clear current session

• Sessions are saved to .girb/sessions/<session_id>.json
• Sessions inactive for 7+ days are automatically deleted
• Resuming with the same session ID continues the previous conversation
• Use get_session_history tool to reference past conversations

Use girb command instead of irb:

girb

Or insert binding.girb in your code:

def problematic_method
  result = some_calculation
  binding.girb  # AI-powered IRB starts here
  result
end

Ctrl+Space: Press after typing your question

irb(main):001> Why did this fail?[Ctrl+Space]

qq command: Use the qq method

irb(main):001> qq How do I use this method?

irb(main):001> x = [1, 2, 3]
irb(main):002> What methods can I use to find the sum?[Ctrl+Space]
You can use `x.sum` which returns 6. Alternatively, `x.reduce(:+)` or `x.inject(0, :+)`.

Add to your Gemfile:

group :development do
  gem 'girb'
  gem 'girb-ruby_llm'
end

bundle install

Create .girbrc in your Rails project root. See Configuration for details.

Just run rails console - girb loads automatically via Railtie:

rails console

irb(main):001> user = User.find(1)
irb(main):002> user.update(name: "test")
=> false
irb(main):003> Why did the update fail?[Ctrl+Space]
Checking `user.errors.full_messages` shows:
- "Email can't be blank"
The email attribute is being cleared during the update.

Step-through debugging with AI assistance.

Same .girbrc as above.

Add require "debug" and require "girb", then use debugger statement:

Note: require "debug" must come before require "girb".

require "debug"
require "girb"

def calculate(x)
  result = x * 2
  debugger  # Stops here with AI assistance
  result + 1
end

calculate(5)

Run with ruby:

ruby your_script.rb

Create an initializer to load girb after debug gem:

# config/initializers/girb.rb
require "girb" if Rails.env.development? || Rails.env.test?

Then use debugger statement in your code:

def show
  @user = User.find(params[:id])
  debugger  # Stops here with AI assistance
end

• qq <question> - Ask AI a question
• Ctrl+Space - Send current input to AI
• Natural language - Non-ASCII input (e.g., Japanese) automatically routes to AI

(rdbg) qq What is the value of result here?
(rdbg) 次の行に進んで[Ctrl+Space]

The AI can run debugger commands for you:

(rdbg) qq Step through this loop and tell me when x becomes 1

The AI will use step, next, continue, break, etc. automatically.

Press Ctrl+C to interrupt long-running AI operations. The AI will summarize progress.

(rdbg) qq Track all values of x through this loop and report when done

[AI sets breakpoints, runs continue, collects values]

Tracked values of x: [7, 66, 85, 11, 53, 42, 99, 23]
Loop completed.

Implement your own LLM provider:

class MyProvider < Girb::Providers::Base
  def initialize(api_key:)
    @api_key = api_key
  end

  def chat(messages:, system_prompt:, tools:, binding: nil)
    # Call your LLM API
    response = call_my_llm(messages, system_prompt, tools)

    Girb::Providers::Base::Response.new(
      text: response.text,
      function_calls: response.tool_calls&.map { |tc| { name: tc.name, args: tc.args } }
    )
  end
end

• Ruby 3.2.0+
• IRB 1.6.0+ (for IRB/Rails usage)
• debug gem (for rdbg usage)
• An LLM provider gem

MIT License

Bug reports and feature requests welcome at GitHub Issues.