Pocketrb

Gem Version CI License

A pocket-sized Ruby AI agent framework with multi-LLM support and advanced capabilities.

Features

  • Clean async architecture: MessageBus, proper tool_use API, async processing
  • Multi-LLM support: Claude (API + Max/OAuth), OpenRouter, OpenAI-compatible APIs, RubyLLM
  • Multi-channel: CLI, Telegram, WhatsApp (via bridge)
  • Advanced features: Planning system, context compaction, runtime skills system
  • Simple memory: JSON-based memory with keyword matching (no external dependencies)
  • Media support: Vision (images) via Claude, document handling
  • Scheduling: Cron jobs for automated tasks
  • Personas: Separate memory and identity from workspace for portable agent personalities

Installation

gem install pocketrb

Or add to your Gemfile:

gem 'pocketrb'

Quick Start

# Set your API key
export ANTHROPIC_API_KEY=your-key

# Initialize a workspace
pocketrb init

# Start chatting
pocketrb chat

Usage

CLI Chat

pocketrb chat [options]

Options:

  • -m, --model MODEL - Model to use (default: claude-sonnet-4-20250514)
  • -p, --provider PROVIDER - LLM provider (anthropic, openrouter, ruby_llm)
  • -w, --workspace DIR - Workspace directory for file access
  • -M, --memory-dir DIR - Memory/persona directory (default: same as workspace)
  • -s, --system-prompt TEXT - Custom system prompt

Telegram Bot

export TELEGRAM_BOT_TOKEN=your-bot-token
pocketrb telegram --allowed-users your_username

Options:

  • -t, --token TOKEN - Bot token (or use env var)
  • -u, --allowed-users - Restrict access to specific usernames/IDs
  • -w, --workspace - File access directory
  • -M, --memory-dir - Persona/memory directory

WhatsApp Bot

Requires the whatsapp-web.js bridge running.

pocketrb whatsapp --bridge-url ws://localhost:3001 --allowed-users +1234567890

Separating Workspace from Memory (Personas)

Run with full filesystem access but a specific persona's memory:

pocketrb telegram \
  --workspace / \
  --memory-dir ~/.pocketrb/personas/koda \
  --token "$TELEGRAM_BOT_TOKEN" \
  --allowed-users your_username

This gives the agent:

  • Full filesystem access via --workspace /
  • Koda's personality and memory via --memory-dir

Personas

Personas allow you to give the agent a persistent identity and memory separate from the working directory.

Directory Structure

~/.pocketrb/personas/my-agent/

IDENTITY.md

Defines who the agent is. Loaded into the system prompt automatically.

# Agent Identity

## Who I Am

**Name:** Assistant
**Role:** Helpful AI assistant
**Personality:** Friendly, direct, technically skilled

## How I Work

- I verify before claiming things are done
- I explain what I'm doing when executing commands
- I ask for clarification when requirements are unclear

## Communication Style

- Concise and direct
- Technical when appropriate
- No unnecessary pleasantries

MEMORY.md

Background knowledge the agent should always have access to.

# Background Knowledge

## User Information

- **Name**: John
- **Timezone**: UTC+1
- **Preferences**: Prefers Python over JavaScript

## Project Context

- Working on a web scraping project
- Database is PostgreSQL 16
- Deployment target is AWS Lambda

Skills

Skills are reusable prompts that extend the agent's capabilities.

Creating Skills

Create a skill in skills/skill-name/SKILL.md:

---
name: code-review
description: Review code for quality and best practices
triggers:
  - review
  - code review
  - check this code
metadata:
  emoji: "🔍"
  requires:
    bins: []
---

# Code Review Skill

When reviewing code, analyze:

1. **Correctness**: Does it do what it's supposed to?
2. **Readability**: Is the code clear and well-organized?
3. **Performance**: Any obvious inefficiencies?
4. **Security**: Input validation, injection risks, etc.
5. **Edge cases**: What happens with unexpected input?

Provide specific, actionable feedback with line numbers.

Skill Frontmatter

Field Description
name Skill identifier
description Short description shown in skill list
triggers Phrases that activate this skill
always If true, always loaded into context
metadata.emoji Display emoji
metadata.requires.bins Required binaries (e.g., ["git", "docker"])
metadata.os Supported OS (e.g., ["linux", "darwin"])

Built-in Skills

Pocketrb includes several built-in skills:

  • github - GitHub CLI operations (gh pr, gh issue, etc.)
  • tmux - Tmux session management for isolated workspaces
  • weather - Weather forecasts via wttr.in

Listing Skills

pocketrb skills

Runtime Skill Creation

The agent can create new skills at runtime using the skill_create tool:

Create a skill called "deploy" that guides deployment to production

Tools

File Operations

Tool Description
read_file Read file contents with line numbers
write_file Write content to a file
edit_file Search/replace editing
list_dir List directory contents

Execution

Tool Description
exec Execute shell commands (auto-backgrounds long commands)
spawn Spawn background subagents for parallel work

Web

Tool Description
web_search Search the web (requires BRAVE_API_KEY)
web_fetch Fetch and extract content from URLs

Planning & Memory

Tool Description
think Internal reasoning for complex problems
plan Create and manage multi-step execution plans
memory Store and search long-term memory

Communication

Tool Description
message Send messages to channels (Telegram, WhatsApp)

Providers

Anthropic (default)

export ANTHROPIC_API_KEY=sk-ant-...
pocketrb chat --provider anthropic

Claude Max (OAuth)

For Claude Max subscribers:

export ANTHROPIC_OAUTH_TOKEN=your-oauth-token
pocketrb chat --provider anthropic

OpenRouter

Access multiple models:

export OPENROUTER_API_KEY=your-key
pocketrb chat --provider openrouter --model anthropic/claude-sonnet-4

Memory System

Pocketrb uses a simple, dependency-free memory system:

Static Memory

  • MEMORY.md - Static background knowledge loaded into every conversation
  • IDENTITY.md - Agent personality and instructions

Dynamic Memory

The agent can store and recall facts using the memory tool:

Categories:

  • learned - Things the agent has learned (e.g., "deployment process")
  • user - User information (e.g., "timezone: UTC+1")
  • preference - User preferences (e.g., "coding_style: functional")
  • context - General context (e.g., "database: PostgreSQL 16")

Storage:

  • Facts stored in memory/facts.json
  • Recent events in memory/recent.json
  • Simple keyword matching for relevance (no vector DB required)

Usage:

Agent: I'll remember that your timezone is UTC+1
[Uses memory tool: store, category: user, key: "timezone", value: "UTC+1"]

User: What's my timezone?
Agent: [Recalls from memory] Your timezone is UTC+1

Scheduling

Cron Jobs

Schedule recurring tasks:

# Add a job that runs every hour
pocketrb cron add --name "hourly-check" --message "Check system status" --every 3600

# Add a cron-style job (9am daily)
pocketrb cron add --name "morning-report" --message "Generate daily report" --cron "0 9 * * *"

# Add a one-time job
pocketrb cron add --name "reminder" --message "Meeting in 10 minutes" --at "2026-02-03T14:50:00"

# List jobs
pocketrb cron list

# Remove a job
pocketrb cron remove job_id

Gateway Mode

Run all services together:

pocketrb gateway \
  --telegram-token "$TELEGRAM_BOT_TOKEN" \
  --telegram-users your_username \
  --enable-cron

Context Compaction

Long conversations are automatically summarized to save tokens:

  • Triggers after 40 messages or ~50k tokens
  • Keeps last 15 messages intact
  • Summarizes older messages using the LLM
  • Falls back to basic summary if LLM fails

Configuration

Config File

Located at workspace/.pocketrb/config.yml or ~/.pocketrb/config.yml:

provider: anthropic
model: claude-sonnet-4-20250514
max_iterations: 50

Commands

pocketrb config show
pocketrb config set model claude-opus-4-20250514
pocketrb config get model

Environment Variables

Variable Description
ANTHROPIC_API_KEY Anthropic API key
ANTHROPIC_OAUTH_TOKEN Claude Max OAuth token
OPENROUTER_API_KEY OpenRouter API key
BRAVE_API_KEY Brave Search API key (for web_search tool)
TELEGRAM_BOT_TOKEN Telegram bot token
POCKETRB_PROVIDER Default provider (anthropic, openrouter, ruby_llm, claude_cli)
POCKETRB_MODEL Default model
POCKETRB_LOG_LEVEL Log level (debug, info, warn, error)

Architecture

Development

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run specific test
bundle exec rspec spec/unit/tools/read_file_spec.rb

# Interactive console
bundle exec irb -r ./lib/pocketrb

License

MIT License - see LICENSE.txt