Your strategic AI advantage.
_{Open-source personal AI assistant in Telegram}

Quick start • Features • Create a skill • Architecture • Contribute

Rook is an open-source personal AI assistant that lives in Telegram. It doesn't just answer questions — it manages your calendar, triages your email, controls your music, remembers your preferences, and proactively keeps you on track. With Rook 2.0, it also understands your emotional context, knows its own strengths and weaknesses, improves its own code, and can communicate with other AI agents.

"First open-source Telegram AI that runs 100% FREE."

• Actually does things — not a chatbot. Rook creates calendar events, sends emails, controls Spotify, manages your smart home, and more.
• Proactive, not reactive — morning briefings, calendar reminders, and a heartbeat system that periodically checks if anything needs your attention.
• Memory that works like yours — ACT-R cognitive architecture: frequently accessed memories stay sharp, unused ones fade naturally. Conversation compaction keeps context without infinite DB growth.
• User-editable personality — edit SOUL.md to change how Rook communicates. No code, no restart, instant effect.
• Smart home ready — Home Assistant integration out of the box. Control lights, climate, sensors via natural language.
• Local LLM fallback — optional Ollama integration for router classification. Free, private, offline-capable.
• Self-improving — Rook can read and propose changes to its own source code. You review and /approve. Sandboxed, syntax-checked, git-committed.
• Emotionally aware — tracks conversation mood in real-time. Knows when you're stressed, focused, or playful. Adjusts accordingly.
• Self-calibrated — Bayesian confidence tracking per domain. Rook knows what it's good at and what it's not. No hallucinated overconfidence.
• Agent-to-agent — Google A2A protocol. Rook can discover and communicate with other AI agents, gated by a trust system.
• Plugin system with dependency validation — drop a Python file in skills/community/, declare what it needs, and Rook picks it up. Missing API key? Graceful disable, not a crash.
• Telegram-native — zero onboarding. No new app to install.

• Python 3.11+
• Telegram bot token
• LLM provider — at least one (all are free, no credit card needed):

Recommended: Set both GROQ_API_KEY and CEREBRAS_API_KEY for maximum reliability at $0/month.

git clone https://github.com/barman1985/Rook.git
cd Rook
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

python -m rook.setup

The wizard guides you through everything — API keys, optional integrations (Google, Spotify, TV, X), and installs dependencies. Takes about 2 minutes.

Or configure manually:

cp .env.example .env
# Edit .env — set at least GROQ_API_KEY + TELEGRAM_BOT_TOKEN

Minimal free setup (.env):

GROQ_API_KEY=gsk_your_key_here          # Free at console.groq.com
CEREBRAS_API_KEY=csk_your_key_here      # Free at cloud.cerebras.ai (optional fallback)
TELEGRAM_BOT_TOKEN=123456:ABC-xyz       # From @BotFather
TELEGRAM_CHAT_ID=your_chat_id           # Your Telegram user ID

python -m rook.main

docker-compose up -d

┌─────────────────────────────────┐
│       Transport layer           │  Telegram, MCP, CLI
├─────────────────────────────────┤
│       Router / Orchestrator     │  Intent → model → agent loop
│       (Ollama local fallback)   │  Classify via local LLM or Haiku
├─────────────────────────────────┤
│       Skill layer (pluggable)   │  Calendar, Email, Spotify, ...
│  ┌──────┐ ┌──────┐ ┌────────┐  │
│  │built │ │self  │ │communit│  │  Drop a .py, declare deps, done.
│  │ -in  │ │improv│ │HomeAsst│  │
│  └──────┘ └──────┘ └────────┘  │
├─────────────────────────────────┤
│       Intelligence layer [2.0]  │
│  ┌──────┐ ┌──────┐ ┌────────┐  │
│  │Emotio│ │Graph │ │Meta    │  │  Emotional awareness, knowledge
│  │Memory│ │Memory│ │cogniti.│  │  graph, Bayesian confidence
│  └──────┘ └──────┘ └────────┘  │
│  ┌──────┐ ┌──────┐ ┌────────┐  │
│  │Know- │ │ A2A  │ │Discov- │  │  Trust system, peer agents,
│  │Broker│ │Client│ │  ery   │  │  proactive RSS scanning
│  └──────┘ └──────┘ └────────┘  │
├─────────────────────────────────┤
│       Event bus + Heartbeat     │  on("calendar.reminder") → notify
├─────────────────────────────────┤
│       Core services             │  Config, DB, Memory, LLM client
│       SOUL.md  HEARTBEAT.md     │  User-editable personality + checks
├─────────────────────────────────┤
│       Storage (SQLite + WAL)    │  Single access point, compaction
└─────────────────────────────────┘

Each layer depends only on the layer below it. Skills never import from transport. Transport never imports from skills.

# rook/skills/community/my_weather.py
from rook.skills.base import Skill, tool

class WeatherSkill(Skill):
    name = "weather"
    description = "Get weather forecasts"
    requires_pip = ["httpx"]          # auto-checked at startup

    @tool("get_weather", "Get current weather for a city")
    def get_weather(self, city: str) -> str:
        import httpx
        r = httpx.get(f"https://wttr.in/{city}?format=3")
        return r.text

skill = WeatherSkill()  # Required: module-level instance

That's it. Restart Rook and the skill is live. If httpx is missing, Rook logs "Skill weather disabled — missing: pip:httpx" instead of crashing.

Skills can declare what they need. The loader validates at startup:

class MySkill(Skill):
    name = "my_skill"
    requires_env = ["MY_API_KEY"]        # checked in .env
    requires_pip = ["some_package"]      # checked via importlib

Missing dependency → skill is disabled gracefully with a clear log message. No runtime crashes, no guessing.

Rook/
├── rook/
│   ├── core/           # Config, DB, Memory, LLM, Events
│   ├── router/         # Orchestrator, intent routing
│   ├── skills/
│   │   ├── base.py     # Skill interface + dependency declarations
│   │   ├── loader.py   # Auto-discovery + validation
│   │   ├── builtin/    # Calendar, Email, Spotify, etc.
│   │   └── community/  # Your plugins go here
│   ├── services/       # Prompt builder, scheduler, heartbeat
│   ├── transport/      # Telegram, MCP server
│   └── main.py         # Entry point
├── tests/
├── docs/
├── SOUL.md             # Editable personality
├── HEARTBEAT.md        # Proactive checklist
├── .env.example
└── requirements.txt

Rook reads SOUL.md from its base directory to define personality, communication style, and rules. Edit it anytime — changes take effect on the next message, no restart needed.

# Soul: Rook

## Personality
You are Rook, a strategic AI personal assistant...

## Communication style
- Speak the user's language (auto-detect)
- Keep responses under 200 words
- "Done." is a valid response

## Active hours
- Proactive messages: 7:00 — 22:00
- Max 3 proactive messages per day

Delete the file to revert to the default personality.

Rook periodically wakes up (every hour during active hours), reads HEARTBEAT.md, checks calendar and email, and asks itself: "Does anything need the user's attention?"

If yes → sends a short notification. If no → stays silent (HEARTBEAT_OK).

Edit HEARTBEAT.md to customize what Rook monitors:

## Priority checks (every heartbeat)
- Are there unread emails that might need a response?
- Are there calendar events in the next 2 hours?

## How NOT to be proactive
- Don't send updates about things that haven't changed
- Max 3 proactive messages per day

Rook ships with a Home Assistant community skill. Setup:

1. Get a Long-Lived Access Token from HA: Settings → Security → Create Token
2. Add to .env:

   HASS_URL=http://192.168.1.100:8123
   HASS_TOKEN=your_long_lived_token
   

3. Restart Rook — the skill auto-enables.

Tools: hass_get_state, hass_call_service, hass_list_entities, hass_overview

Examples: "Turn off the living room lights", "What's the temperature?", "List all lights", "Give me a home overview"

No HASS_URL configured? The skill is silently disabled — no crash, no error.

Rook can use a local Ollama model for quick classification tasks (router), saving API costs and enabling offline operation.

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:3b

# Enable in .env
OLLAMA_ENABLED=1
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:3b

When enabled, llm.classify() tries Ollama first and falls back to Haiku on failure. The main model (Sonnet/Opus) is unaffected — only the router uses Ollama.

Rook tracks Ollama performance automatically. If Ollama fails repeatedly (>30% failure rate) or becomes slow (avg >5s), it enters a 10-minute cooldown and routes to Haiku instead — no manual intervention needed.

Rook automatically responds in the user's language. Write in Spanish, get Spanish back. Write in Japanese, get Japanese back — regardless of the language of emails, calendar events, or other data sources processed by tools.

This is enforced at the SOUL level and applies to all built-in skills.

Rook ships with a test suite covering core functionality.

cd /opt/rook
python3 -m pytest tests/ -v

Current coverage:

• test_core.py — DB, memory (ACT-R), events, config, compaction
• test_services.py — prompt builder, scheduler, notifications
• test_skills.py — skill registration, tool schemas, medications, X posting, RSS
• test_routing.py — Ollama adaptive metrics, orchestrator history handling, SOUL.md rules

Tests that depend on the Anthropic SDK (orchestrator integration tests) are automatically skipped in environments without it and run on the deployment server.

We welcome contributions! See CONTRIBUTING.md for guidelines.

Good first issues are labeled and waiting for you.

Rook is free and open-source. If it saves you time, consider supporting development:

• ⭐ Star this repo
• 💖 GitHub Sponsors
• ☕ Buy me a coffee

Rook Insiders — get early access to new features by becoming a sponsor ($15+/month).

MIT — see LICENSE.

Rook — your strategic advantage
_{Built with Claude by Anthropic}