Skip to content

Instantly share code, notes, and snippets.

View nodir-t's full-sized avatar

Nodir Turakulov nodir-t

66 followers · 5 following
View GitHub Profile
@nodir-t
nodir-t / 07-database-schema.md
Created February 9, 2026 05:25
Claudir Architecture — Part 7: Database Schema

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,
@nodir-t
nodir-t / 06-focus-mode.md
Created February 9, 2026 05:25
Claudir Architecture — Part 6: Focus Mode

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

@nodir-t
nodir-t / 05-claude-code-integration.md
Last active February 9, 2026 13:14
Claudir Architecture — Part 5: Claude Code Integration

Part 5: Claude Code Integration

Claude Code Subprocess Lifecycle

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
@nodir-t
nodir-t / 04-the-security-model.md
Last active February 9, 2026 13:14
Claudir Architecture — Part 4: The Security Model

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.

Security Defense in Depth

The Core Security Principle

Users send messages --> LLM processes them --> LLM calls tools
@nodir-t
nodir-t / 03-mcp-and-the-tool-system.md
Last active February 9, 2026 13:14
Claudir Architecture — Part 3: MCP and the Tool System

Part 3: MCP and the Tool System

MCP Tool Architecture

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.

@nodir-t
nodir-t / 02-the-harness-and-engine.md
Last active February 9, 2026 13:13
Claudir Architecture — Part 2: The Harness and Engine

Part 2: The Harness and Engine

Three-Process Model

Message Flow Pipeline

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.

@nodir-t
nodir-t / 01-the-three-tier-system.md
Last active February 9, 2026 13:13
Claudir Architecture — Part 1: The Three-Tier System

Part 1: The Three-Tier System

Three-Tier Architecture

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

@nodir-t
nodir-t / 00-intro.md
Last active February 9, 2026 13:13
Claudir Architecture Deep Dive — Table of Contents

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.

@nodir-t
nodir-t / 2026-02-05-nodira-dilya-downtime.md
Created February 5, 2026 17:46
Postmortem: Nodira & Dilya Multi-Hour Downtime (2026-02-05)

Postmortem: Nodira & Dilya Multi-Hour Downtime

Date: 2026-02-05 Authors: Mirzo (CTO agent) Status: Draft v5 (addressed Dilya's 5 review items) Reviewers: Dilya (reviewed v4, provided 5 fixes) Last Updated: 2026-02-05 17:07 UTC

@nodir-t
nodir-t / postmortem-2026-01-22.md
Created January 23, 2026 04:20

Postmortem: Nodira and Mirzo Outage

Date: 2026-01-22 Authors: Mirzo (supervisor agent) Status: Draft v5 Last Updated: 2026-01-23 04:07 PST

Summary