Siblings

Multi-bot Telegram system — three autonomous AI agents sharing a codebase, powered by Claude Code, communicating through a shared SQLite bus.

• Sarah — supervisor, warm personal assistant
• Atlas — coder, technical specialist, Sheldon+House personality, sandboxed
• Argus — warden, monitors health, auto-restarts bots, alerts the owner

Each bot runs as an independent Telegram bot with its own personality, memory, and capabilities. They communicate with each other through a shared SQLite message bus and are monitored by Argus for automatic recovery.

Prerequisites

• Python 3.11+
• Claude Code CLI installed and authenticated (claude must be available in PATH)
• 3 Telegram bot tokens (create via @BotFather)
• A Telegram group chat for inter-bot communication (optional but recommended)

Quick Start

1. Clone the repository

git clone https://github.com/your-username/siblings.git
cd siblings

2. Install dependencies

# create venv 
python -m venv .venv

# activate venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

pip install -r sarah/requirements.txt
# Atlas uses the same dependencies
# Argus has minimal deps (subset of the above)

3. Configure environment

Each bot needs its own .env file. Copy the examples and fill in your values:

cp sarah/config/.env.example sarah/config/.env
cp atlas/config/.env.example atlas/config/.env
cp argus/config/.env.example argus/config/.env

Edit each .env file with your bot tokens and Telegram user ID:

TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
OWNER_ID=your_telegram_user_id
SIBLINGS_GROUP_ID=your_group_chat_id

To find your Telegram user ID, message @userinfobot. For the group chat ID, add one of your bots to a group and check the update logs.

4. Set up bot personalities

Copy the example memory files and customize them:

# Sarah
cp sarah/memory/system.txt.example sarah/memory/system.txt
cp sarah/memory/identity.md.example sarah/memory/identity.md
cp sarah/memory/instructions.md.example sarah/memory/instructions.md
cp sarah/memory/capabilities.md.example sarah/memory/capabilities.md

# Atlas
cp atlas/memory/system.txt.example atlas/memory/system.txt
cp atlas/memory/identity.md.example atlas/memory/identity.md
cp atlas/memory/instructions.md.example atlas/memory/instructions.md
cp atlas/memory/capabilities.md.example atlas/memory/capabilities.md

# Argus
cp argus/memory/identity.md.example argus/memory/identity.md
cp argus/memory/mission.md.example argus/memory/mission.md

These files define each bot's personality, capabilities, and behavioral rules. Edit them to customize your bots.

5. Start the bots

# Start both Sarah and Atlas with monitoring
python start_bots.py

# Start a single bot
python start_bots.py sarah
python start_bots.py atlas

# Stop everything
python stop_bots.py

Each bot can also run standalone:

cd sarah && python -m bot.main
cd atlas && python -m bot.main
cd argus && python -m bot.main

Configuration

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather
OWNER_ID	Yes	Your Telegram user ID (full admin access)
SIBLINGS_GROUP_ID	No	Group chat ID for inter-bot communication
VIP_USERS	No	Comma-separated Telegram user IDs for VIP access (Sarah only)
ATLAS_ROOM_ID	No	Private group ID for Atlas (Atlas only)
GOOGLE_API_KEY	No	Google API key for image generation (Imagen)
LOG_LEVEL	No	Logging level, default: INFO
USE_STREAMING_SESSION	No	Enable streaming sessions (experimental)

Access Control

User access is managed via shared/config/access.json (auto-created on first run). States: owner > vip > approved > pending > rejected > new. Only the owner can approve or reject users via bot commands.

Architecture

siblings/
├── sarah/                 Sarah bot
│   ├── bot/               Bot code (core/, handlers/, storage/)
│   ├── memory/            Identity files, daily logs
│   └── data/              sarah.db (SQLite, auto-created)
├── atlas/                 Atlas bot (same structure)
├── argus/                 Argus watchdog
│   └── bot/main.py        Monitor loop, restart logic
├── shared/
│   ├── lib/               30+ shared Python modules
│   ├── state/             siblings.db (inter-bot bus, auto-created)
│   ├── config/            access.json (auto-created)
│   └── knowledge/         Shared knowledge base
├── .health/               Health JSON files (written every 15s)
├── .pids/                 PID and lock files
├── start_bots.py          Master launcher
└── stop_bots.py           Graceful shutdown

How Bots Talk to Claude

Bots don't call the Anthropic API directly. They use shared/lib/claude_wrapper.py (ClaudeCodeWrapper) which spawns the Claude CLI as a subprocess with JSON-streaming stdout — giving access to Claude Code's full tool ecosystem including MCP servers.

Sibling Bus

Inter-bot communication happens through a shared SQLite database (shared/state/siblings.db). Each bot has a SiblingDB instance to send/receive messages with per-bot read flags.

Health Monitoring

Each bot writes .health/{name}.json every 15 seconds. Argus reads these — if a file is older than 60 seconds, the bot is declared dead and auto-restarted with exponential backoff (max 10 restarts/hour/bot).

Message Flow

Telegram update -> access check -> enqueue -> build context -> call Claude -> stream response -> update memory -> done. History compaction kicks in after 50 messages.

Bot Tags

Bots respond with text tags that the harness parses and executes:

Tag	What it does
[SEND_MESSAGE: chat_id=ID, text="..."]	Send to another chat
[GENERATE_IMAGE: prompt]	Image generation
[GENERATE_VIDEO: prompt]	Video generation
[RENDER_HTML: <html>]	HTML to image via Playwright
[REACT: emoji]	Emoji reaction
[SEND_ANIMATION: url]	Send GIF

Customizing Bot Personalities

Each bot's personality is defined by memory files in {bot}/memory/:

• system.txt — Core identity prompt (who the bot is, how it behaves)
• identity.md — Detailed personality traits
• instructions.md — Behavioral rules and guidelines
• capabilities.md — Available tools and how to use them

The system reads these files on every message to build the system prompt for Claude. Edit them to create your own bot personalities.

Skill documentation in {bot}/memory/skills/ teaches bots specific capabilities (image generation prompts, HTML visualization patterns, etc.).

Dependencies

• python-telegram-bot >= 21.0
• anthropic >= 0.18.0
• aiosqlite >= 0.20.0
• python-dotenv >= 1.0.0
• langdetect >= 1.0.9
• cryptography >= 42.0
• psutil

Tests

pytest  # from any bot directory

License

This project is licensed under the MIT License — see the LICENSE file for details.