Configuration

Maestro uses environment variables for runtime settings and YAML files for agent configuration.

Environment Variables

Create a .env file in the project root:

cp .env.example .env

Required

Variable	Description
ANTHROPIC_API_KEY	Your Anthropic API key

Optional

Variable	Default	Description
TELEGRAM_BOT_TOKEN	—	Telegram bot token from @BotFather
GITHUB_TOKEN	—	GitHub token for private repos
PORT	3000	REST API port
LOG_LEVEL	info	Logging level (debug, info, warn, error)
DAILY_BUDGET_LIMIT	—	Maximum API cost per day in USD
MONTHLY_BUDGET_LIMIT	—	Maximum API cost per month in USD

Budget Guardrails

Set spending limits to prevent runaway costs:

DAILY_BUDGET_LIMIT=10.00
MONTHLY_BUDGET_LIMIT=100.00

When limits are reached, Maestro will refuse new requests until the period resets.

Agent Configuration

Static agents are defined in YAML files under config/:

config/personal-assistant.yaml

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.

tools:
  - calculator
  - datetime

Agent Fields

Field	Required	Description
name	Yes	Unique identifier for the agent
description	Yes	What this agent does (used by orchestrator for routing)
model.provider	Yes	LLM provider (anthropic)
model.name	Yes	Model name (e.g., claude-sonnet-4-20250514)
model.temperature	No	Response randomness (0-1, default: 0.7)
model.max_tokens	No	Max response length (default: 4096)
system_prompt	Yes	Instructions for the agent
tools	No	List of tool names to enable

Available Tools

Tool	Description
calculator	Evaluate math expressions
datetime	Get current time/date with timezone
clone_project	Clone a git repository
switch_project	Switch between projects
list_projects	List all cloned projects
current_project	Show active project
claude_code	Execute coding tasks
create_agent	Create dynamic agents
update_agent	Modify agent configuration
list_agents	List all agents
delete_agent	Remove dynamic agents

Tip

Dynamic agents created through conversation have the same configuration options. They’re stored in SQLite and can be managed with the agent tools.

GitHub Token Setup

To clone private repositories:

1. Go to github.com/settings/tokens
2. Generate new token (classic)
3. Select the repo scope
4. Add to .env:

GITHUB_TOKEN=ghp_xxxxx

This token works for all repositories you have access to, including organization repos.

Directory Structure

maestro/
├── config/           # Agent YAML files
├── data/             # SQLite database (auto-created)
├── logs/             # Log files (auto-created)
├── projects/         # Cloned repositories (auto-created)
└── .env              # Environment configuration

All data directories are gitignored by default.