CLAUDE.md

CLAUDE.md

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

Project Overview

CMBAgent is a multi-agent system powered by AG2 (formerly AutoGen) for scientific discovery across scientific domains. The system follows a planning and control strategy with specialized agents for different research workflows.

The system uses a two-phase approach:

• Planning: A planner and plan reviewer design task execution strategies
• Control: Step-by-step execution where sub-tasks are handed to specialized agents

Key Components

Core Python Package (cmbagent/)

• Main API: cmbagent.one_shot() - primary function for task execution
• Agent system: Specialized agents in agents/ directory, each with .py and .yaml configuration
• Agent types: Planning, control, coding (engineer, executor), research (researcher, summarizer), hypothesis generation, keyword extraction, and domain-specific templates
• Context management: Sophisticated context handling via context.py and hand_offs.py
• Remote execution: execution/remote_executor.py - delegates code execution to client

Common Development Commands

Python Package

# Install core only (lightweight)
pip install -e .

# Install with development tools
pip install -e ".[dev]"

# Install with local execution support (if not using remote execution)
pip install -e ".[local]"

# Install everything (all scientific packages)
pip install -e ".[all]"

# Run tests (individual Python scripts in tests/)
python tests/test_one_shot.py
python tests/test_engineer.py

Architecture Details

Agent System

• Each agent has a Python implementation and YAML configuration
• Agents are specialized for different workflows: engineering, research, planning, execution, hypothesis generation, keyword extraction
• Response formatters handle output formatting for specific use cases
• Controller manages workflow orchestration
• Domain-specific agents in specialized/ serve as templates for users to add their own

Multi-Modal Capabilities

• Plot generation capabilities
• File browser with inline image viewing

Research Capabilities

• Domain-agnostic architecture supporting any scientific field
• Literature search and keyword extraction (literature.py, aas_keyword_finder)
• Example domain packages provided: materials science, biochemistry, astronomy, data science
• Users can easily add their own domain-specific dependencies in pyproject.toml

Work Directory Structure

Tasks create organized output directories:

project_dir/
├── chats/          # Conversation history
├── codebase/       # Generated code
├── cost/           # Cost analysis
├── data/           # Generated data and plots
├── time/           # Timing reports
└── context/        # Context files (.pkl)

Testing

• Tests are individual Python scripts in tests/ directory
• Run specific test files directly: python tests/test_<name>.py
• Tests cover various agents and use cases (engineering, research, plotting, etc.)
• No centralized test runner - tests are designed as standalone demonstrations

Configuration

• API keys required: OPENAI_API_KEY, optionally ANTHROPIC_API_KEY, GEMINI_API_KEY
• Model configurations in cmbagent/apis/ (JSON files for different providers)
• Agent configurations in individual .yaml files alongside Python implementations

Key APIs

• cmbagent.one_shot(task, agent='engineer', model='gpt-4o', work_dir=...) - Main execution API
• Planning and control via specialized agent orchestration
• WebSocket streaming for real-time UI updates