mithai: Instructions file for Claude Code

CLAUDE.md

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

What is mithai

An AI agent framework for infrastructure operations. It gives teams an AI-powered ops agent (backed by Claude) that lives in Slack, Telegram, and a terminal simultaneously. The agent uses skills (plugins) to take actions and Human MCP for human-in-the-loop approval of risky operations.

Common Commands

# Install dependencies (uses uv)
uv pip install -e ".[dev]"

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_engine_images.py

# Run a single test by name
uv run pytest tests/test_tool_router.py -k "test_route_calls_handler"

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Build native binary
make build-binary

Architecture

Core Loop

Adapter (Slack/Telegram/CLI) → Engine → LLM (Claude API)
                                  ↓            ↓
                              ToolRouter    Tool calls
                                  ↓       (skill__tool namespacing)
                              Skill handler or MCP server
                                  ↓
                              HumanMCP (approve/confirm/auto)

Engine (src/mithai/core/engine.py) — Central orchestrator. Builds system prompt from skill prompts, runs the LLM tool-use loop with Human MCP checks. Adapter-agnostic: the adapter is passed per-call so one engine can serve multiple adapters.

ToolRouter (src/mithai/core/tool_router.py) — Namespaces tools as skill_name__tool_name (double underscore separator). Routes LLM tool calls back to the correct skill handler or MCP server. Enforces allowed_tools for multi-agent mode.

Adapters (src/mithai/adapters/) — Platform-specific message transport. All extend Adapter base class. IncomingMessage and OutgoingMessage are platform-agnostic dataclasses.

HumanMCP (src/mithai/human/mcp.py) — Human-in-the-loop protocol. Tools declare their level: None (auto), "approve", "confirm", or "dynamic" (resolved at runtime by skill's resolve_human() function). Config overrides in config.yaml can escalate or de-escalate.