@Rustam-Z 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.

The Three-Tier System — Owner/Supervisor, CTO bot, public chatbots. Trust hierarchy, bot-to-bot messaging, config-driven personalities, self-healing wrapper.
The Harness and Engine — Three-process model, message flow pipeline, spam filtering, debouncer, control loop, inject mechanism, dropped text detection.

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

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.

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.

	import os
	import sys

	print(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
	sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

	<html>
	<body bgcolor=black>
	<center>
	<h2><font color=yellow>Hello from Mars!</font></h2>
	<font color=red>Rustam-Z</font>
	</center>
	</body>
	</html>

	import importlib

	# Contrived example of generating a module named as a string
	full_module_name = "tables." + "tasks"

	# The file gets executed upon import, as expected.
	mymodule = importlib.import_module(full_module_name)

	# Then you can use the module like normal
	var = mymodule.COLUMNS

	venv/*
	.*
	*.pyc
	__pycache__*/

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


	class SingletonType(type):
	_instances = {}

	import pathlib

	print(pathlib.Path(__file__).parent.absolute())