Skip to content

Installation

Requirements

  • Ruby >= 3.3.0
  • Bundler (recommended)

Basic Installation

Add SharedTools to your Gemfile:

gem 'shared_tools'
gem 'ruby_llm'  # Required LLM framework

Then install:

bundle install

Or install directly:

gem install shared_tools

Dependencies

SharedTools has the following core dependencies that are automatically installed:

  • ruby_llm - Ruby LLM framework for tool integration
  • zeitwerk - Code autoloading
  • nokogiri - HTML/XML parsing
  • dentaku - Mathematical expression evaluation (CalculatorTool)
  • openweathermap - Weather API client (WeatherTool)
  • sequel - SQL toolkit (DatabaseQueryTool)

Optional Dependencies

Depending on which tools you plan to use, you may need additional gems:

Browser Automation

For the BrowserTool:

gem 'watir'

Watir also requires a browser driver. Install ChromeDriver:

# macOS
brew install --cask chromedriver

# Ubuntu/Debian
apt-get install chromium-chromedriver

Database Operations

For the DatabaseTool:

gem 'sqlite3'   # SQLite
gem 'pg'        # PostgreSQL

Document Processing

For the DocTool:

gem 'pdf-reader', '~> 2.0'   # PDF support
gem 'docx'                    # Microsoft Word (.docx) support
gem 'roo'                     # Spreadsheet support: CSV, XLSX, ODS, XLSM

Install all three to support all document formats:

gem install pdf-reader docx roo

Code Evaluation

The EvalTool requires:

  • Ruby (already installed)
  • Python 3 (for Python evaluation)
  • Shell access (for shell commands)

Install Python 3:

# macOS
brew install python3

# Ubuntu/Debian
apt-get install python3

MCP Clients

SharedTools bundles optional MCP (Model Context Protocol) clients. Each is opt-in via an extra require:

gem 'ruby_llm-mcp', '>= 0.7.0'   # Add to Gemfile
Transport What's needed
Remote HTTP (Tavily) Only an API key — no binaries
Brew-installed (GitHub, Notion, Slack, Hugging Face) Homebrew — binaries are auto-installed on first use
npx (Memory, Sequential Thinking, Chart, Brave Search, Playwright) Node.js / npx — packages are auto-downloaded on first use

See MCP Clients README for full configuration details.

Complete Setup Example

For a full-featured installation with all optional dependencies:

# Gemfile
gem 'shared_tools'
gem 'ruby_llm'

# Browser automation
gem 'watir'

# Database
gem 'sqlite3'
gem 'pg'

# Document processing
gem 'pdf-reader'
gem 'docx'
gem 'roo'

Then run:

bundle install

Verify Installation

Create a test script to verify SharedTools is installed correctly:

# test_install.rb
require 'shared_tools'

puts "SharedTools version: #{SharedTools::VERSION}"
puts "RubyLLM detected: #{defined?(RubyLLM::Tool) ? 'Yes' : 'No'}"

# Test basic tool initialization
disk = SharedTools::Tools::DiskTool.new
puts "DiskTool initialized successfully!"

Run it:

ruby test_install.rb

Expected output:

SharedTools version: 0.x.x
RubyLLM detected: Yes
DiskTool initialized successfully!

Troubleshooting

Zeitwerk Errors

If you see autoloading errors, ensure you're using Ruby >= 3.3.0:

ruby --version

Missing Browser Driver

If BrowserTool fails with "browser not found":

  1. Install a browser (Chrome, Firefox)
  2. Install the corresponding driver (chromedriver, geckodriver)
  3. Ensure the driver is in your PATH

SQLite3 Compilation Issues

On macOS, if the sqlite3 gem fails to install:

gem install sqlite3 -- --with-sqlite3-include=/usr/local/opt/sqlite/include \
                        --with-sqlite3-lib=/usr/local/opt/sqlite/lib

DocTool — Missing Gem for Format

If DocTool raises a LoadError when reading a specific format, install the corresponding gem:

gem install pdf-reader   # for PDF
gem install docx         # for Word documents
gem install roo          # for CSV, XLSX, ODS

Next Steps