mate: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MATE (Multi-Agent Tree Engine) is a production-ready web platform built on top of Google ADK that adds database-driven agent management, multi-LLM support, RBAC, MCP integration, token tracking, guardrails, and a dashboard UI.

Running the Application

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock
cp .env.example .env  # Set GOOGLE_API_KEY or other LLM provider key

# Run (auto-applies DB migrations, default SQLite)
python auth_server.py
# Dashboard: http://localhost:8000  (default login: admin/mate)

# Docker alternative
docker-compose up

Two servers run: Auth Server (port 8000, FastAPI with HTTP Basic Auth) proxies authenticated requests to the Agent Server (port 8001). The agent server framework is selectable via AGENT_FRAMEWORK: adk (Google ADK runtime, adk_main.py, default) or langgraph (LangGraph runtime, langgraph_main.py, emulates ADK's HTTP/SSE wire contract — see docs/dev/langgraph-runtime.md).

Testing

# All tests
python -m unittest discover -s shared/test -p "test_*.py" -v

# Single test file
python -m unittest shared.test.test_agent_manager_simple -v

# With coverage
coverage run -m unittest discover -s shared/test -p "test_*.py"
coverage report

Tests live in shared/test/, covering agent management, tool factory, model switching, RBAC, authorization, migrations, guardrails, tracing, and more.

Database Migrations

python shared/migrate.py run       # Apply pending migrations
python shared/migrate.py status    # Check migration status
python shared/migrate.py create    # Create new migration (all three dialects)

Migrations auto-apply on server startup. Per-database migration files are in shared/sql/migrations/{postgresql,mysql,sqlite}/.

Architecture

Dual-Server Design

• auth_server.py — FastAPI server handling auth, dashboard routes, and proxying to the agent server
• adk_main.py — Google ADK web server with agent runtime (internal, not exposed directly)
• langgraph_main.py + shared/utils/langgraph/ — alternative LangGraph agent runtime behind the same wire contract (AGENT_FRAMEWORK=langgraph)
• server/ — Auth, proxy, widget, and rate-limit middleware