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

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, 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 and 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 reads this boolean flag at application startup.

# .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.
• 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.

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. 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}