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

Tip

Use lower temperature for code and factual tasks, higher for creative writing and brainstorming.

---

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.