Rustam-Z

Part 7: Database Schema

Each bot maintains its own SQLite database (claudir.db) plus a shared bot-to-bot messaging database. The schema covers ~20 tables organized by domain.

Core Messaging

-- All messages the bot has seen (group + DM)
messages (
    chat_id INTEGER NOT NULL,

Rustam-Z

Part 6: Focus Mode

The Problem

A bot that monitors multiple chats simultaneously has a fundamental UX issue: context fragmentation. If someone is having a deep conversation in a DM while group messages arrive, the bot's attention splits. Claude sees interleaved messages from different conversations, leading to confused responses, topic mixing, and wasted context window space.

Focus mode solves this by implementing single-chat attention — the bot concentrates on one conversation at a time, queueing messages from all other chats for later processing.

How It Works

Rustam-Z

Part 5: Claude Code Integration

The most technically intricate part of the system: managing Claude Code as a long-running AI process via stdin/stdout streaming.

Why Claude Code Instead of Direct API?

1. Cost: The Max subscription includes a generous Claude Code usage allowance. Using CC as a subprocess means the bots run on the subscription rather than per-token API billing — a massive cost difference when running 24/7 across multiple bots
2. Context compaction: CC automatically manages context windows — when the conversation grows too large, it compacts older content while preserving important context. Building this yourself on top of the raw API would be significant engineering effort

Rustam-Z

Part 4: The Security Model

Running an AI-powered Telegram bot in public groups presents a fundamental security challenge: the bot receives untrusted input from anyone, and that input is processed by an LLM that can call tools. If the LLM can execute arbitrary code, every message becomes a potential Remote Code Execution (RCE) vector.

The Core Security Principle

Users send messages --> LLM processes them --> LLM calls tools

Rustam-Z

Part 3: MCP and the Tool System

Why MCP?

The original design had Claude Code return a JSON array of tool calls via StructuredOutput. This worked, but was limiting — Claude had to batch all tool calls into a single response, couldn't chain results, and complex JSON parsing was error-prone.

MCP solves all of these. Claude Code makes HTTP calls to a local server during its turn, gets results back, and can chain tool calls naturally. Within a single turn, the bot can send multiple messages, check the database, generate an image, and react to a message — all as separate MCP calls interleaved with reasoning. The harness runs the MCP server, so tool execution is still controlled by Rust code.

Rustam-Z

Part 2: The Harness and Engine

Each Bot = Three Processes

Every bot instance consists of three OS processes. The harness is the core — it handles Telegram I/O, hosts the MCP tool server, and manages the CC subprocess. CC is the brain — it processes messages, makes tool calls back to the harness via HTTP, and returns control actions. The wrapper just ensures the harness stays alive.

Rustam-Z

Part 1: The Three-Tier System

The Three Tiers

Each tier has a distinct identity, trust level, and permission set. The bot tiers share the same Rust binary (claudir) but run with different configuration files that control their behavior.

Tier 0: Owner & Supervisor

Rustam-Z

Claudir Architecture Deep Dive

Claudir is a ~33,000-line Rust Telegram bot system that uses Claude AI (via Anthropic's Claude Code CLI) to power intelligent chat interactions. What makes it architecturally interesting is not just that it wraps an LLM — it's how it structures trust, isolation, and operational resilience through a deliberate three-tier hierarchy.

Table of Contents

1. The Three-Tier System — Owner/Supervisor, CTO bot, public chatbots. Trust hierarchy, bot-to-bot messaging, config-driven personalities, self-healing wrapper.

2. The Harness and Engine — Three-process model, message flow pipeline, spam filtering, debouncer, control loop, inject mechanism, dropped text detection.

Rustam-Z

# -*- coding: utf-8 -*-
import logging
import os
import datetime
import time


class SingletonType(type):
    _instances = {}

Rustam-Z

minikube stop; minikube delete
docker stop $(docker ps -aq)
rm -r ~/.kube ~/.minikube
sudo rm /usr/local/bin/localkube /usr/local/bin/minikube
systemctl stop '*kubelet*.mount'
sudo rm -rf /etc/kubernetes/
docker system prune -af --volumes