Architecture

Maestro follows a layered architecture where each component has a clear responsibility.

Overview

┌─────────────────────────────────────────────────────────────┐
│                        CHANNELS                              │
│              [Telegram]  [CLI]  [REST API]                   │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      ORCHESTRATOR                            │
│              Routes requests to specialized agents           │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                         AGENTS                               │
│         [Personal Assistant]  [Coder]  [+ Custom]            │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                    INFRASTRUCTURE                            │
│   [Memory/SQLite]  [Tools]  [Projects]  [Observability]      │
└─────────────────────────────────────────────────────────────┘

Layers

Channels

Channels are interfaces that receive user input and return responses. Each channel:

• Receives messages from a specific platform (Telegram, CLI, HTTP)
• Transforms platform-specific formats into a common message format
• Routes messages to the orchestrator
• Returns responses in the platform’s expected format

All channels connect to the same orchestrator and share memory.

Orchestrator

The orchestrator is a specialized agent that:

1. Analyzes incoming messages to understand intent
2. Decides which agent is best suited to handle the request
3. Routes the request to that agent
4. Returns the agent’s response

The orchestrator has access to agent metadata (names, descriptions) but doesn’t do the actual work.

Agents

Agents are LLM-powered workers with specific roles:

• System prompt defining their personality and capabilities
• Tools they can use (calculator, datetime, code execution)
• Model configuration (which Claude model, temperature, etc.)

Agents can be:

• Static: Defined in YAML files under config/
• Dynamic: Created at runtime through conversation

Infrastructure

Shared services that all components use:

• Memory: SQLite-backed conversation persistence
• Tools: Registry of capabilities agents can use
• Projects: Git repository management
• Observability: Logging, token tracking, cost estimation

Request Flow

1. User sends "Help me write a Python script"
   ↓
2. Telegram channel receives message
   ↓
3. Channel passes message to orchestrator
   ↓
4. Orchestrator analyzes: "This is a coding task"
   ↓
5. Orchestrator routes to coder agent
   ↓
6. Coder agent:
   - Loads conversation history from memory
   - Calls Claude with system prompt + history + tools
   - Executes tools if needed (claude_code)
   - Returns response
   ↓
7. Response flows back through channel to user

Data Flow

Memory

Each conversation is identified by a session ID:

• Telegram: Chat ID
• CLI: Fixed ID per terminal session
• API: Provided by caller

Memory stores:

• Message history (user messages, assistant responses)
• Tool calls and results
• Session metadata

Projects

The project system maintains isolated workspaces:

• Each cloned repo gets its own directory
• Agents operate within the active project’s context
• Claude Code runs commands in the project directory

Code Organization

src/
├── agents/            # Orchestrator logic
├── api/               # REST API (Hono framework)
├── channels/          # Telegram, CLI adapters
├── core/              # Agent runtime, types, registry
├── llm/               # Anthropic provider
├── memory/            # SQLite persistence
├── observability/     # Logging, cost tracking
└── tools/             # Tool system
    └── builtin/       # Built-in tools

Note

The modular design makes it straightforward to add new channels, tools, or agents without modifying existing code.