# How MessageOrchestrator Differentiates Agentic vs Classic Bot Modes in Claude Code Telegram

> Discover how MessageOrchestrator route Telegram updates between agentic and classic bot modes using the agentic_mode flag. Learn the handler differences for each mode.

- Repository: [Richard A/claude-code-telegram](https://github.com/richardatct/claude-code-telegram)
- Tags: internals
- Published: 2026-02-20

---

**The `MessageOrchestrator` routes Telegram updates to entirely different handler sets based on the `agentic_mode` boolean flag in application settings, registering minimal conversational handlers for agentic mode versus a full 13-command classic suite.**

The `MessageOrchestrator` in the `RichardAtCT/claude-code-telegram` repository serves as the central entry point for all Telegram updates. This component determines whether the bot operates in **agentic mode**—a streamlined conversational interface—or **classic mode**, which provides a comprehensive command-driven experience. The routing decision occurs at startup based on a single configuration flag.

## Mode Detection via the Agentic Mode Flag

At initialization, the orchestrator checks `self.settings.agentic_mode` to determine which handler registration path to execute. This boolean flag, defined in [`src/config/settings.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/config/settings.py), acts as the primary switch between operational modes. When `register_handlers` is called, the orchestrator branches to either `_register_agentic_handlers` or `_register_classic_handlers` based on this evaluation【/src/bot/orchestrator.py#L75-L80】.

## Agentic Mode: Minimal Conversational Interface

When agentic mode is enabled, the orchestrator registers a lightweight handler set designed for direct AI interaction. The `_register_agentic_handlers` method wires six core commands: `start`, `new`, `status`, `verbose`, `repo`, and conditionally `sync_threads` when project thread support is enabled【/src/bot/orchestrator.py#L82-L99】.

Beyond commands, this mode registers generic handlers for text messages, documents, and photos that immediately forward content to Claude AI without intermediate processing【/src/bot/orchestrator.py#L100-L121】. This architecture eliminates complex UI flows in favor of a simple conversational pipeline.

## Classic Mode: Full Command Suite

When `agentic_mode` is disabled, the orchestrator invokes `_register_classic_handlers` to load a comprehensive 13-command interface. This suite includes rich UI components such as inline keyboards and multi-step workflows that the agentic mode deliberately omits【/src/bot/orchestrator.py#L133-L155】.

The classic handlers import from [`src/bot/handlers/command.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/bot/handlers/command.py) and [`src/bot/handlers/message.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/bot/handlers/message.py), providing features like `help_command`, `git_command`, and complex document processing workflows. This mode prioritizes feature richness over conversational simplicity.

## Dependency Injection Across Both Modes

Regardless of the active mode, the orchestrator wraps every handler with `_inject_deps` before registration. This method injects shared services—including storage adapters, rate limiters, and Claude AI integrations—into `context.bot_data` prior to handler execution【/src/bot/orchestrator.py#L107-L119】.

This consistent dependency injection pattern ensures that both agentic and classic handlers access the same underlying infrastructure, maintaining service parity despite their differing interface designs.

## Configuration: Enabling Agentic Mode

To switch between modes, modify the `AGENTIC_MODE` environment variable or update the `.env` configuration file. The `Settings` class in [`src/config/settings.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/config/settings.py) reads this boolean flag at application startup.

```bash

# .env

AGENTIC_MODE=true        # Enable minimal conversational UI

```

When set to `true`, the orchestrator registers agentic handlers; when `false` or undefined, it defaults to the classic command suite.

## Summary

- The `MessageOrchestrator` uses the `agentic_mode` boolean flag to determine operational mode at startup.
- **Agentic mode** registers minimal handlers (`start`, `new`, `status`, `verbose`, `repo`, plus generic text/file handlers) for direct AI conversation.
- **Classic mode** loads a full 13-command suite with rich UI components from [`src/bot/handlers/command.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/bot/handlers/command.py).
- Both modes use `_inject_deps` to ensure consistent service injection into `context.bot_data`.
- Configuration occurs via the `AGENTIC_MODE` environment variable in [`src/config/settings.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/config/settings.py).

## Frequently Asked Questions

### What triggers the MessageOrchestrator to choose agentic mode over classic mode?

The orchestrator checks `self.settings.agentic_mode` during initialization. This boolean value originates from the `AGENTIC_MODE` environment variable defined in [`src/config/settings.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/config/settings.py). When `true`, the orchestrator calls `_register_agentic_handlers`; otherwise, it executes `_register_classic_handlers`.

### Which specific commands are available in agentic mode compared to classic mode?

Agentic mode exposes six core commands: `start`, `new`, `status`, `verbose`, `repo`, and optionally `sync_threads` when project threads are enabled. Classic mode provides thirteen commands including `help`, `git`, and others with rich inline keyboards and multi-step workflows defined in [`src/bot/handlers/command.py`](https://github.com/RichardAtCT/claude-code-telegram/blob/main/src/bot/handlers/command.py).

### How does the orchestrator ensure handlers have access to shared services in both modes?

Every handler registered in either mode is wrapped with `_inject_deps`, which populates `context.bot_data` with shared services including storage adapters, rate limiters, and Claude AI integrations before the handler executes. This ensures consistent infrastructure access regardless of the active mode.

### Can I switch between agentic and classic modes without restarting the application?

No, the mode selection occurs during handler registration at application startup in the `register_handlers` method. Changing the `AGENTIC_MODE` environment variable requires restarting the bot to trigger re-registration of the appropriate handler set.