# 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
```bash
# 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