RubyLLM Coding Agent

An AI coding agent built with Ruby and the RubyLLM gem. This command-line tool lets you converse with an AI assistant that can list directories, read files, and edit code in your project.

Features

• 🤖 Interactive Chat Interface - Conversational interface for natural language interactions
• 📁 Directory Listing - Browse and explore project structure
• 📄 File Reading - Read and analyze file contents
• ✏️ File Editing - Modify files with search and replace operations
• 💰 Cost Tracking - Monitor token usage and estimated API costs per request
• 🔒 Security - Restricted file access (no dotfiles) and directory sandboxing

Project Structure

.
├── Gemfile                      # Ruby dependencies
├── Gemfile.lock                 # Locked gem versions
├── run_agent.rb                 # Main executable entry point
├── simple_agent.rb              # Core agent implementation
├── directory_listing_tool.rb    # Tool for listing directory contents
├── read_file_tool.rb            # Tool for reading file contents
├── edit_file_tool.rb            # Tool for editing files
├── rubyllm-coding-agent-plan.md # Detailed implementation guide
└── ruby_llm.log                 # API interaction logs

Prerequisites

• Ruby (2.7 or higher recommended)
• Bundler
• An API key from one of the supported providers:
  • OpenRouter (recommended)
  • OpenAI
  • Anthropic

Installation

1. Clone or download this project

2. Install dependencies:

   bundle install

3. Configure environment variables:

   Create a .env.local file in the project root:

   WELCOME_MESSAGE="Hello! I'm your coding assistant."
   OPENROUTER_KEY=your_openrouter_api_key_here

   Alternatively, you can use other providers by setting:

   • OPENAI_API_KEY for OpenAI
   • ANTHROPIC_API_KEY for Anthropic

4. Make the script executable:

   chmod +x run_agent.rb

Usage

Starting the Agent

Run the agent from the command line:

./run_agent.rb

Example Interactions

List project files:

>> What files are in this directory?

Read a specific file:

>> Show me the contents of simple_agent.rb

Analyze dependencies:

>> What gems does this project use?

Edit a file:

>> Change the welcome message in simple_agent.rb to say "Welcome to the AI Coding Assistant"

Exit the conversation:

>> exit

(or type quit or bye)

Tools

DirectoryListingTool

Lists files and directories at a given path, returning name, type, and size information.

ReadFileTool

Reads the contents of files within the project directory. Prevents reading dotfiles for security.

EditFileTool

Performs search-and-replace operations on files. Creates new files if they don't exist. Only allows editing files in the current directory or subdirectories.

Configuration

The agent is configured in run_agent.rb with the following settings:

• Model: anthropic/claude-sonnet-4.5 (via OpenRouter)
• API Base: https://openrouter.ai/api.v1
• Logging: Enabled with debug level to ruby_llm.log

You can modify these settings in the RubyLLM.configure block.

Cost Tracking

After each interaction, the agent displays:

• Estimated cost for the request
• Input and output token counts
• Total tokens used in the conversation

Example output:

---
Estimated cost: $0.001234
Conversation total tokens: 1523

Security Features

• Dotfile Protection: Cannot read or edit files starting with . (like .env.local)
• Directory Sandboxing: File operations restricted to current directory and subdirectories
• Error Handling: Graceful error messages for invalid operations

Dependencies

• ruby_llm - Core LLM framework for Ruby
• dotenv - Environment variable management
• json - JSON parsing and generation
• pastel - Terminal text coloring
• rspec - Testing framework

Development

Extending with New Tools

To add a new tool, create a class that inherits from RubyLLM::Tool:

class MyTool < RubyLLM::Tool
  description "What this tool does"
  param :my_param, type: :string, desc: "Parameter description"

  def execute(my_param:)
    # Tool implementation
  end
end

Then register it in simple_agent.rb:

@chat.with_tool(MyTool)

Tutorial

This project includes a comprehensive tutorial in rubyllm-coding-agent-plan.md that walks through building the agent from scratch, covering:

• Basic Ruby environment setup
• RubyLLM configuration
• Building interactive conversation loops
• Creating custom tools
• Implementing cost tracking
• Security considerations

Resources

• RubyLLM Documentation
• RubyLLM GitHub
• OpenRouter

License

This is a tutorial project. Feel free to use and modify as needed.

Contributing

This is an educational project based on the RubyLLM coding agent tutorial. Feel free to fork and experiment with your own enhancements!

Troubleshooting

API Key Issues:

• Ensure your .env.local file exists and contains valid API keys
• Check that the API key has sufficient credits

Tool Execution Errors:

• Verify file paths are relative to the project directory
• Check file permissions for read/write operations

Unexpected Behavior:

• Check ruby_llm.log for detailed API interaction logs
• Ensure you're using compatible Ruby version (2.7+)