RubyCode

A terminal-based agentic coding assistant powered by RubyLLM.

RubyCode is a Ruby port of the Claude Code TypeScript CLI. It runs an agentic loop in your terminal -- the LLM can read files, edit code, run shell commands, search your codebase, and more, all with your permission.

Install

gem "ruby_code"

Or install directly:

gem install ruby_code

Setup

Set your API key:

export ANTHROPIC_API_KEY=sk-ant-...

Other providers work too (set the relevant key):

export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...

Usage

Start the interactive REPL:

ruby_code

Or with options:

ruby_code chat --model claude-sonnet-4-6
ruby_code chat --max-turns 10
ruby_code chat --system-prompt "You are a Ruby expert."

Non-interactive mode (pipe in a prompt):

echo "Explain this codebase" | ruby_code chat --print

Slash Commands

Command	Description
/help	Show available commands
/model [name]	Show or switch the active model
/cost	Show session cost and token usage
/clear	Clear conversation history
/compact	Force context compaction
/status	Show session status
/config	View configuration
/diff	Show file changes in this session
/init	Initialize project config (CLAUDE.md)
/memory	View CLAUDE.md
/doctor	Run diagnostics
/vim	Toggle vim keybindings
/stats	Detailed session statistics
/permissions	View permission rules
/exit	Exit the REPL

Tools

RubyCode has 13 built-in tools the LLM can use:

• Read -- read files with line numbers
• Write -- create or overwrite files
• Edit -- find-and-replace in files
• Glob -- search for files by pattern
• Grep -- search file contents (ripgrep)
• Bash -- run shell commands
• WebSearch -- search the web
• WebFetch -- fetch URL content
• NotebookEdit -- edit Jupyter notebooks
• TodoWrite -- manage a session todo list
• Agent -- spawn a subagent for complex tasks
• AskUser -- ask structured questions
• Sleep -- wait

Configuration

Configure in Ruby:

require "ruby_code"

RubyCode.configure do |config|
  config.anthropic_api_key = "sk-ant-..."
  config.default_model = "claude-sonnet-4-6"
  config.request_timeout = 120
  config.max_retries = 3
end

Settings are stored in ~/.ruby_code/settings.json. Project-level settings go in .ruby_code/settings.json.

CLAUDE.md

Create a CLAUDE.md file in your project root to give the assistant persistent instructions:

ruby_code chat
> /init

MCP Servers

RubyCode supports MCP servers via ruby_llm-mcp:

client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", Dir.pwd] }
)

Architecture

The core is a simple agentic loop:

User prompt → LLM call → tool calls? → execute tools → feed results back → repeat

RubyCode uses RubyLLM::Chat for message history but calls the provider directly (provider.complete) for each turn, bypassing the auto-execution loop. This gives full control over permission checks, streaming, abort handling, and budget tracking.

Development

git clone https://github.com/ruby-code/ruby_code
cd ruby_code
bundle install
bundle exec rake test

License

MIT