Configuration Reference

Environment Variables

Create a .env file in the project root:

API Keys

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Anthropic API key for Claude
`GITHUB_TOKEN`	No	GitHub token for private repositories

Channel Configuration

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	For Telegram	Bot token from @BotFather
`PORT`	No	REST API port (default: 3000)

Budget Guardrails

Variable	Default	Description
`DAILY_BUDGET_LIMIT`	unlimited	Max daily API cost in USD
`MONTHLY_BUDGET_LIMIT`	unlimited	Max monthly API cost in USD

Logging

Variable	Default	Description
`LOG_LEVEL`	`info`	Logging level: debug, info, warn, error

Agent Configuration

Agents are configured via YAML files in config/.

Full Schema

# Required fields
name: string              # Unique identifier
description: string       # Used for routing decisions

# Model configuration
model:
  provider: anthropic     # LLM provider
  name: string            # Model ID (e.g., claude-sonnet-4-20250514)
  temperature: number     # 0-1, default 0.7
  max_tokens: number      # Max response tokens, default 4096

# Agent behavior
system_prompt: string     # Instructions for the agent

# Capabilities
tools:                    # List of enabled tool names
  - calculator
  - datetime

Example: Personal Assistant

name: personal-assistant
description: General-purpose assistant for everyday tasks

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.7
  max_tokens: 4096

system_prompt: |
  You are a helpful personal assistant. Be concise and helpful.
  Use tools when they would help answer the user's question.
  Be friendly but professional.

tools:
  - calculator
  - datetime

Example: Coder Agent

name: coder
description: Programming and code execution via Claude Code

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.3
  max_tokens: 8192

system_prompt: |
  You are a coding assistant. Help users with programming tasks.
  Use the claude_code tool to read files, write code, and run commands.
  Always explain what you're doing before executing code.

tools:
  - claude_code
  - current_project
  - list_projects
  - switch_project
  - clone_project

Example: Orchestrator

name: orchestrator
description: Routes requests to specialized agents

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.3
  max_tokens: 1024

system_prompt: |
  You are an orchestrator. Analyze user requests and route them
  to the most appropriate specialized agent.

  Available agents will be provided in the context.
  Respond with the agent name that should handle the request.

tools:
  - list_agents

Model Options

Supported Models

Model ID	Description
`claude-sonnet-4-20250514`	Fast, capable
`claude-opus-4-20250514`	Most capable
`claude-haiku-3-20240307`	Fastest, cheapest

Temperature Guidelines

Value	Use Case
0.0-0.3	Factual, consistent responses
0.4-0.6	Balanced creativity
0.7-1.0	Creative, varied responses

Tool Configuration

Available Tools

Tool	Description
`calculator`	Math expression evaluation
`datetime`	Current time with timezone
`clone_project`	Clone git repository
`switch_project`	Change active project
`list_projects`	List cloned projects
`current_project`	Show active project
`claude_code`	Execute coding tasks
`create_agent`	Create dynamic agent
`update_agent`	Modify agent config
`list_agents`	List all agents
`get_agent`	Get agent details
`delete_agent`	Remove dynamic agent

Tool Selection

Only enable tools an agent needs:

# General assistant
tools:
  - calculator
  - datetime

# Coder
tools:
  - claude_code
  - current_project
  - switch_project

# Agent manager
tools:
  - create_agent
  - update_agent
  - list_agents
  - delete_agent

Directory Structure

maestro/
├── config/               # Agent YAML files
│   ├── orchestrator.yaml
│   ├── personal-assistant.yaml
│   └── coder-agent.yaml
├── data/                 # SQLite database (auto-created)
│   └── maestro.db
├── logs/                 # Log files (auto-created)
├── projects/             # Cloned repositories (auto-created)
├── .env                  # Environment configuration
└── docker-compose.yml

All data directories (data/, logs/, projects/) are gitignored.