SharedTools

Two Robots sharing the same set of tools

A Ruby gem providing LLM-callable tools for browser automation, file operations, code evaluation, document processing, network queries, data science, workflow management, and more

Overview

SharedTools is a comprehensive collection of production-ready tools designed for LLM (Large Language Model) applications. Built on the RubyLLM framework, it provides a unified interface for common automation tasks while maintaining safety through a human-in-the-loop authorization system.

Key Features

🔧 21+ Production Tools — Browser automation, file operations, database queries, code evaluation, document processing, DNS and WHOIS lookups, IP geolocation, data science, weather data, workflow management, system utilities, notifications, and more
🔒 Human-in-the-Loop Authorization — Built-in safety system for sensitive operations
🎯 Facade Pattern — Simplified interfaces with complex capabilities under the hood
🔌 Pluggable Drivers — Swap implementations for testing or different backends
📚 Comprehensive Documentation — Detailed guides, examples, and API reference
✅ Well Tested — 85%+ test coverage with Minitest

Installation

Add to your Gemfile:

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

Or install directly:

gem install shared_tools

Optional Dependencies

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

# For BrowserTool
gem 'watir'

# For DatabaseTool and DatabaseQueryTool
gem 'sqlite3'  # or pg, mysql2, etc.

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

# Core dependencies (automatically installed)
gem 'dentaku'        # For CalculatorTool
gem 'openweathermap' # For WeatherTool
gem 'sequel'         # For DatabaseQueryTool
gem 'nokogiri'       # For various tools

Quick Start

require 'shared_tools'
require 'ruby_llm'

# Initialize an LLM agent with SharedTools
chat = RubyLLM.chat.with_tools(
  SharedTools::Tools::BrowserTool.new,
  SharedTools::Tools::DiskTool.new,
  SharedTools::Tools::DnsTool.new,
  SharedTools::Tools::WeatherTool.new,
  SharedTools::Tools::WorkflowManagerTool.new
)

# Use with human-in-the-loop authorization (default)
chat.ask("Visit example.com and save the page title to title.txt")
# User will be prompted: "Allow BrowserTool to visit https://example.com? (y/n)"

# Or enable auto-execution for automated workflows
SharedTools.auto_execute(true)
chat.ask("Calculate the square root of 144 and tell me the weather in London")

Tool Collections

🌐 Browser Tools

Web automation and scraping capabilities.

Actions: visit, page_inspect, ui_inspect, selector_inspect, click, text_field_set, screenshot

browser = SharedTools::Tools::BrowserTool.new
browser.execute(action: "visit", url: "https://example.com")
browser.execute(action: "page_inspect", full_html: false)

📖 Full Browser Documentation

💾 Disk Tools

Secure file system operations with path traversal protection.

Actions: file_create, file_read, file_write, file_delete, file_move, file_replace, directory_create, directory_list, directory_move, directory_delete

disk = SharedTools::Tools::DiskTool.new
disk.execute(action: "file_create", path: "./report.txt")
disk.execute(action: "file_write", path: "./report.txt", text: "Hello, World!")
content = disk.execute(action: "file_read", path: "./report.txt")

📖 Full Disk Documentation

🗄️ Database Tools

Execute SQL operations on databases.

Features: SELECT, INSERT, UPDATE, DELETE; read-only query mode; automatic LIMIT enforcement; pluggable drivers (SQLite, PostgreSQL, MySQL)

require 'sqlite3'

db = SQLite3::Database.new(':memory:')
driver = SharedTools::Tools::Database::SqliteDriver.new(db: db)
database = SharedTools::Tools::DatabaseTool.new(driver: driver)

results = database.execute(
  statements: [
    "CREATE TABLE users (id INTEGER, name TEXT)",
    "INSERT INTO users VALUES (1, 'Alice')",
    "SELECT * FROM users"
  ]
)

📖 Full Database Documentation

💻 Eval Tools

Safe code evaluation for Ruby, Python, and shell commands.

Languages: ruby, python, shell

eval_tool = SharedTools::Tools::EvalTool.new
result = eval_tool.execute(language: "ruby", code: "puts 2 + 2")
output = eval_tool.execute(language: "shell", code: "ls -la")

📖 Full Eval Documentation

📄 Doc Tools

Read and reason over documents in any format.

Actions: text_read, pdf_read, docx_read, spreadsheet_read

doc = SharedTools::Tools::DocTool.new

# Plain text
doc.execute(action: "text_read", doc_path: "./notes.txt")

# PDF — specific pages or ranges
doc.execute(action: "pdf_read", doc_path: "./report.pdf", page_numbers: "1, 5-10")

# Microsoft Word
doc.execute(action: "docx_read", doc_path: "./meeting.docx")

# Spreadsheets (CSV, XLSX, ODS, XLSM)
doc.execute(action: "spreadsheet_read", doc_path: "./data.xlsx", sheet: "Q1 Sales")

📖 Full Doc Documentation

🌐 DNS Tool

DNS resolution, WHOIS queries, IP geolocation, and external IP detection. No API key required.

Actions: a, aaaa, mx, ns, txt, cname, reverse, all, external_ip, ip_location, whois

dns = SharedTools::Tools::DnsTool.new

dns.execute(action: "mx", host: "gmail.com")
dns.execute(action: "whois", host: "ruby-lang.org")
dns.execute(action: "external_ip")
dns.execute(action: "ip_location")           # geolocate your own IP
dns.execute(action: "ip_location", host: "8.8.8.8")  # geolocate any IP

📖 Full DNS Documentation

🌤️ Weather Tool

Real-time weather data from OpenWeatherMap API. Combine with DnsTool for automatic local forecasts.

Features: Current conditions, 3-day forecast, metric/imperial/kelvin units, global coverage

weather = SharedTools::Tools::WeatherTool.new
weather.execute(city: "London,UK", units: "metric", include_forecast: true)

Local forecast with automatic location detection:

chat = RubyLLM.chat.with_tools(
  SharedTools::Tools::DnsTool.new,
  SharedTools::Tools::WeatherTool.new,
  SharedTools::Tools::CurrentDateTimeTool.new
)

chat.ask("Get my external IP, find my city, then give me the current weather and 3-day forecast.")

📖 Full Weather Documentation

🧮 Calculator Tool

Safe mathematical calculations without code execution risks.

Features: Arithmetic, math functions (sqrt, round, abs), trigonometry (sin, cos, tan), configurable precision

calculator = SharedTools::Tools::CalculatorTool.new
calculator.execute(expression: "sqrt(16) * 2", precision: 4)
# => {success: true, result: 8.0}

📊 Data Science Kit

Real statistical analysis on actual data — file-based or inline.

Analysis types: statistical_summary, correlation_analysis, time_series, clustering, prediction

Inline data formats: pipe-delimited tables, CSV strings, JSON arrays, comma-separated numbers

kit = SharedTools::Tools::DataScienceKit.new

# From a file
kit.execute(analysis_type: "statistical_summary", data_source: "./sales.csv")

# Inline pipe-delimited table
kit.execute(
  analysis_type: "correlation_analysis",
  data: "| month | revenue | cost |\n| Jan | 12400 | 8200 |\n| Feb | 11800 | 7900 |"
)

📖 Full Data Science Documentation

🖱️ Computer Tools

System-level automation for mouse, keyboard, and screen control.

Actions: mouse_click, mouse_move, mouse_position, type, key, hold_key, scroll, wait

computer = SharedTools::Tools::ComputerTool.new
computer.execute(action: "mouse_click", coordinate: {x: 100, y: 200})
computer.execute(action: "type", text: "Hello, World!")

📖 Full Computer Documentation

🕐 Date/Time, System Info & Clipboard

Utility tools for context and system access:

# Current date and day of week (prevents LLM hallucination)
dt = SharedTools::Tools::CurrentDateTimeTool.new
dt.execute(format: "date")
# => { date: "2026-03-25", day_of_week: "Wednesday", ... }

# System hardware and OS info
info = SharedTools::Tools::SystemInfoTool.new
info.execute

# Clipboard
clipboard = SharedTools::Tools::ClipboardTool.new
clipboard.execute(action: "read")
clipboard.execute(action: "write", text: "Hello!")

🔔 Notification Tool

Cross-platform desktop notifications, modal alert dialogs, and text-to-speech. Supports macOS and Linux with no gem dependencies.

Actions: notify, alert, speak

tool = SharedTools::Tools::NotificationTool.new

# Non-blocking desktop banner
tool.execute(action: "notify", message: "Build complete", title: "CI", sound: "Glass")

# Modal dialog — blocks until user clicks; returns clicked button label
result = tool.execute(action: "alert", message: "Deploy to production?", buttons: ["Yes", "No"])
result[:button]  # => "Yes" or "No"

# Text-to-speech
tool.execute(action: "speak", message: "Task finished", voice: "Samantha", rate: 160)

Action	macOS	Linux
`notify`	osascript	notify-send
`alert`	osascript dialog	zenity or terminal fallback
`speak`	say	espeak-ng / espeak

🔄 Workflow Manager Tool

Persistent multi-step workflow orchestration with JSON file storage.

Actions: start, step, status, complete, list

workflow = SharedTools::Tools::WorkflowManagerTool.new

# Start a workflow
result = workflow.execute(action: "start", step_data: {project: "release-v2.0"})
workflow_id = result[:workflow_id]

# Execute steps
workflow.execute(action: "step", workflow_id: workflow_id, step_data: {task: "run_tests"})
workflow.execute(action: "step", workflow_id: workflow_id, step_data: {task: "deploy"})

# Check status
workflow.execute(action: "status", workflow_id: workflow_id)

# List all workflows
workflow.execute(action: "list")

# Complete
workflow.execute(action: "complete", workflow_id: workflow_id)

📊 Composite Analysis Tool

Multi-stage data analysis orchestration.

analyzer = SharedTools::Tools::CompositeAnalysisTool.new
analyzer.execute(
  data_source: "./sales_data.csv",
  analysis_type: "comprehensive",
  options: {include_correlations: true, visualization_limit: 5}
)

🐳 Docker Compose Tool

Execute Docker Compose commands safely.

docker = SharedTools::Tools::Docker::ComposeRunTool.new
docker.execute(service: "app", command: "rspec", args: ["spec/main_spec.rb"])

🛠️ Error Handling Tool

Reference implementation for robust error handling patterns.

error_tool = SharedTools::Tools::ErrorHandlingTool.new
error_tool.execute(
  operation: "process",
  data: {name: "test", value: 42},
  max_retries: 3
)

MCP Clients

SharedTools bundles Model Context Protocol clients that connect AI agents to external services. Each client is opt-in — require only the ones you need.

Remote HTTP (API key only)

Client	Env var	Provides
`require 'shared_tools/mcp/tavily_client'`	`TAVILY_API_KEY`	Web search, news, research, URL extraction

Brew-installed (auto-installs via Homebrew)

Client	Env var	Provides
`require 'shared_tools/mcp/github_client'`	`GITHUB_PERSONAL_ACCESS_TOKEN`	Repos, issues, PRs, code search
`require 'shared_tools/mcp/notion_client'`	`NOTION_TOKEN`	Pages, databases, search, content CRUD
`require 'shared_tools/mcp/slack_client'`	`SLACK_MCP_XOXP_TOKEN`	Channels, messages, threads, user info
`require 'shared_tools/mcp/hugging_face_client'`	`HF_TOKEN`	Models, datasets, Spaces, model cards

npx Auto-download (Node.js required)

Client	Provides
`require 'shared_tools/mcp/memory_client'`	Persistent knowledge graph
`require 'shared_tools/mcp/sequential_thinking_client'`	Chain-of-thought reasoning
`require 'shared_tools/mcp/chart_client'`	Chart and visualisation generation
`require 'shared_tools/mcp/brave_search_client'`	Web and news search (`BRAVE_API_KEY`)
`require 'shared_tools/mcp/playwright_client'`	Browser automation: navigate, click, fill, screenshot, extract

# Load all available clients at once (skips any whose env vars are missing)
require 'shared_tools/mcp'

# Or load a specific client
require 'shared_tools/mcp/notion_client'
client = RubyLLM::MCP.clients["notion"]
chat   = RubyLLM.chat.with_tools(*client.tools)
chat.ask("Find my project planning pages and summarise what's in them")

See MCP Clients README for full configuration details.

Authorization System

SharedTools includes a human-in-the-loop authorization system for safety:

# Require user confirmation (default)
SharedTools.auto_execute(false)

# The LLM proposes an action
disk.execute(action: "file_delete", path: "./important.txt")
# Prompt: "Allow DiskTool to delete ./important.txt? (y/n)"

# Enable auto-execution for trusted workflows
SharedTools.auto_execute(true)
disk.execute(action: "file_delete", path: "./temp.txt")
# Executes immediately without prompting

📖 Authorization Guide

Documentation

Comprehensive documentation is available at madbomber.github.io/shared_tools

Documentation Sections

Getting Started — Installation, quick start, basic usage
Tool Collections — Detailed documentation for each tool
Guides — Authorization, drivers, error handling, testing
Examples — Working code examples and workflows
API Reference — Tool base class, facade pattern, driver interface
Development — Architecture, contributing, changelog

Examples

The /examples directory contains runnable demonstrations using a shared common.rb helper:

bundle exec ruby -I examples examples/weather_tool_demo.rb
bundle exec ruby -I examples examples/dns_tool_demo.rb
bundle exec ruby -I examples examples/doc_tool_demo.rb

Demo	What it shows
`browser_tool_demo.rb`	Web automation
`calculator_tool_demo.rb`	Math expressions
`clipboard_tool_demo.rb`	Clipboard read/write
`composite_analysis_tool_demo.rb`	Multi-stage analysis
`computer_tool_demo.rb`	Mouse and keyboard
`cron_tool_demo.rb`	Cron scheduling
`current_date_time_tool_demo.rb`	Real date and time
`data_science_kit_demo.rb`	Statistical analysis with inline data
`database_tool_demo.rb`	SQL operations
`database_query_tool_demo.rb`	Read-only SQL queries
`disk_tool_demo.rb`	File operations
`dns_tool_demo.rb`	DNS, WHOIS, geolocation
`doc_tool_demo.rb`	Text, PDF, Word, spreadsheets
`error_handling_tool_demo.rb`	Error handling patterns
`eval_tool_demo.rb`	Code evaluation
`mcp_client_demo.rb`	MCP client overview
`mcp/tavily_demo.rb`	Tavily web search (HTTP)
`mcp/github_demo.rb`	GitHub repos, issues, PRs
`mcp/notion_demo.rb`	Notion pages and databases
`mcp/slack_demo.rb`	Slack channels and messages
`mcp/hugging_face_demo.rb`	Hugging Face models and datasets
`mcp/memory_demo.rb`	Persistent knowledge graph
`mcp/sequential_thinking_demo.rb`	Chain-of-thought reasoning
`mcp/chart_demo.rb`	Chart generation
`mcp/brave_search_demo.rb`	Brave web search
`mcp/playwright_demo.rb`	Browser automation via Playwright
`notification_tool_demo.rb`	Desktop notifications, alerts, TTS
`system_info_tool_demo.rb`	System info
`weather_tool_demo.rb`	Weather + local forecast
`workflow_manager_tool_demo.rb`	Workflow orchestration
`comprehensive_workflow_demo.rb`	Multi-tool pipeline

📖 View All Examples

Development

Setup

git clone https://github.com/madbomber/shared_tools.git
cd shared_tools
bundle install

Running Tests

# Run all tests
bundle exec rake test

# Run specific test file
bundle exec ruby test/shared_tools/tools/browser_tool_test.rb

# Run with SimpleCov coverage report
COVERAGE=true bundle exec rake test

Building Documentation

pip install mkdocs-material
mkdocs serve    # Serve locally
mkdocs build    # Build static site

Code Quality

Testing: Minitest (85%+ coverage)
Code Loading: Zeitwerk for autoloading
Documentation: MkDocs with Material theme
Examples: Executable Ruby scripts in /examples

Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure tests pass (bundle exec rake test)
Open a Pull Request

📖 Contributing Guide

Requirements

Ruby 3.0 or higher
RubyLLM gem for LLM integration

License

This gem is available as open source under the terms of the MIT License.

Special Thanks

This gem was originally inspired by Kevin Sylvestre's omniai-tools gem. SharedTools has since evolved to focus exclusively on RubyLLM support with enhanced features and comprehensive documentation.

Support

Made with ❤️ by Dewayne VanHoozer

shared_tools

Development

Runtime

SharedTools

Overview

Key Features

Installation

Optional Dependencies

Quick Start

Tool Collections

🌐 Browser Tools

💾 Disk Tools

🗄️ Database Tools

💻 Eval Tools

📄 Doc Tools

🌐 DNS Tool

🌤️ Weather Tool

🧮 Calculator Tool

📊 Data Science Kit

🖱️ Computer Tools

🕐 Date/Time, System Info & Clipboard

🔔 Notification Tool

🔄 Workflow Manager Tool

📊 Composite Analysis Tool

🐳 Docker Compose Tool

🛠️ Error Handling Tool

MCP Clients

Remote HTTP (API key only)

Brew-installed (auto-installs via Homebrew)

npx Auto-download (Node.js required)

Authorization System

Documentation

Documentation Sections

Examples

Development

Setup

Running Tests

Building Documentation

Code Quality

Contributing

Requirements

License

Special Thanks

Links

Support