CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Quick Reference
6 
7All commands run from the `classic/` directory (parent of this directory):
8 
9```bash
10# Run interactive CLI
11poetry run autogpt run
12 
13# Run Agent Protocol server (port 8000)
14poetry run serve --debug
15 
16# Run tests
17poetry run pytest original_autogpt/tests/
18poetry run pytest original_autogpt/tests/unit/ -v
19poetry run pytest -k test_name
20```
21 
22## Entry Points
23 
24| Command | Entry | Description |
25|---------|-------|-------------|
26| `autogpt run` | `app/cli.py:run()` | Interactive agent mode |
27| `autogpt serve` | `app/cli.py:serve()` | Agent Protocol server (FastAPI) |
28 
29Both ultimately call functions in `app/main.py`:
30- `run_auto_gpt()` → `run_interaction_loop(agent)`
31- `run_auto_gpt_server()` → Hypercorn + FastAPI
32 
33## Directory Structure
34 
35```
36autogpt/
37├── __main__.py                    # Entry: runs cli()
38├── app/                           # Application layer
39│   ├── cli.py                     # Click CLI (@cli.command decorators)
40│   ├── main.py                    # run_auto_gpt(), run_interaction_loop()
41│   ├── config.py                  # AppConfig (Pydantic) + ConfigBuilder
42│   ├── agent_protocol_server.py   # FastAPI server for Agent Protocol
43│   ├── setup.py                   # Interactive AI profile setup
44│   └── configurator.py            # Config overrides, model validation
45├── agents/                        # Core agent
46│   ├── agent.py                   # Agent class (extends BaseAgent)
47│   ├── agent_manager.py           # State persistence (load/save)
48│   └── prompt_strategies/
49│       └── one_shot.py            # Prompt building + response parsing
50└── agent_factory/                 # Agent creation
51    ├── configurators.py           # create_agent(), configure_agent_with_state()
52    └── profile_generator.py       # AI profile generation
53```
54 
55## Core Architecture
56 
57### Agent Class (`agents/agent.py`)
58 
59Extends `forge.agent.base.BaseAgent[OneShotAgentActionProposal]`.
60 
61**Constructor**:
62```python
63Agent(
64    settings: AgentSettings,      # State: profile, directives, history
65    llm_provider: MultiProvider,  # LLM access
66    file_storage: FileStorage,    # File access
67    app_config: AppConfig,
68)
69```
70 
71**Built-in Components** (initialized in `__init__`):
72- `self.system` - System information
73- `self.history` - ActionHistoryComponent (episodic memory)
74- `self.file_manager` - FileManagerComponent (workspace files)
75- `self.code_executor` - CodeExecutorComponent (Docker-based)
76- `self.git_ops` - GitOperationsComponent
77- `self.image_gen` - ImageGeneratorComponent
78- `self.web_search` - WebSearchComponent
79- `self.web_browser` - WebPlaywrightComponent
80- `self.context` - ContextComponent
81- `self.watchdog` - WatchdogComponent
82- `self.user_interaction` - UserInteractionComponent
83 
84**Key Methods**:
85- `propose_action()` → Builds prompt, calls LLM, returns `OneShotAgentActionProposal`
86- `execute(proposal)` → Runs the proposed tool, returns `ActionResult`
87- `do_not_execute(proposal, feedback)` → Registers user feedback instead
88 
89### Main Loop (`app/main.py:run_interaction_loop`)
90 
91```
92While cycles_remaining > 0:
93  1. agent.propose_action() → ActionProposal (thoughts + tool call)
94  2. Display thoughts + proposed command to user
95  3. Get user feedback (or auto-execute in continuous mode)
96  4. agent.execute(proposal) or agent.do_not_execute(proposal, feedback)
97  5. Decrement cycles, handle Ctrl+C gracefully
98```
99 
100**Cycle Budget**:
101- Normal mode: `cycles = 1` (prompt user each step)
102- Continuous mode: `cycles = continuous_limit or ∞`
103- User can extend: "y -5" gives 5 more cycles
104 
105### Prompt Strategy (`agents/prompt_strategies/one_shot.py`)
106 
107**`OneShotAgentActionProposal`**:
108```python
109thoughts: AssistantThoughts  # observations, reasoning, plan, self_criticism
110use_tool: AssistantFunctionCall  # {name, arguments}
111```
112 
113**`AssistantThoughts`**:
114```python
115observations: str      # From last action result
116text: str              # Main thoughts
117reasoning: str         # Why this thought
118self_criticism: str    # Constructive critique
119plan: list[str]        # Multi-step plan
120speak: str             # What to say to user
121```
122 
123**Prompt Structure**:
1241. System prompt (intro + profile + directives + commands)
1252. Task as user message
1263. Message history from components
1274. "Determine next action" instruction
128 
129### Configuration (`app/config.py`)
130 
131**`AppConfig`** (Pydantic BaseModel):
132```python
133smart_llm: ModelName = "gpt-4-turbo"    # Complex reasoning
134fast_llm: ModelName = "gpt-3.5-turbo"   # Fast operations
135temperature: float = 0.0
136continuous_mode: bool = False
137continuous_limit: int = 0
138restrict_to_workspace: bool = True       # Sandbox file access
139disabled_commands: list[str] = []
140```
141 
142**`ConfigBuilder.build_config_from_env()`** loads from:
1431. Hardcoded defaults
1442. Environment variables
1453. `.env` file
1464. CLI arguments (highest priority)
147 
148### State Persistence
149 
150**Workspace Structure**:
151```
152data/agents/{agent_id}/
153├── state.json          # AgentSettings (profile, directives, history)
154└── workspace/          # Agent's working directory
155```
156 
157**`AgentSettings`** contains:
158- `agent_id`, `task`
159- `ai_profile` (name, role, goals)
160- `ai_directives` (constraints, resources, best practices)
161- `history` (EpisodicActionHistory)
162 
163**`AgentManager`**:
164- `list_agents()` - All agent IDs
165- `load_agent_state(agent_id)` - Load from state.json
166- `save_state()` - Persist current state
167 
168## Memory System
169 
170**Short-term** (within execution):
171- `agent.event_history` (EpisodicActionHistory)
172- Each action creates an `Episode` with action + result
173- Token-limited: oldest episodes dropped when limit exceeded
174 
175**Long-term** (across sessions):
176- Serialized to `state.json` via Pydantic
177- Resume with `AgentManager.load_agent_state()`
178 
179## Component System
180 
181Components implement protocols from forge:
182- `CommandProvider.get_commands()` - Provide available commands
183- `DirectiveProvider.get_*()` - Provide constraints/resources/best practices
184- `MessageProvider.get_messages()` - Provide context messages
185 
186**Execution**: `agent.run_pipeline(Protocol.method)` runs all component implementations.
187 
188**Ordering**: `component.run_after(other)` controls execution order.
189 
190## Forge Dependency
191 
192Heavy reliance on `forge` package (sibling directory):
193- `forge.agent.base.BaseAgent` - Base class
194- `forge.llm.providers.MultiProvider` - LLM abstraction
195- `forge.file_storage` - File storage backends
196- `forge.components.*` - All component implementations
197- `forge.models.config` - Configuration models
198 
199## Key Gotchas
200 
2011. **Component ordering matters** - Use `run_after()` for dependencies
2022. **Token limits are critical** - History auto-drops old episodes; large results get truncated
2033. **Continuous mode is dangerous** - No user approval between steps
2044. **State files grow large** - Full history in state.json
2055. **SIGINT handling** - First Ctrl+C stops continuous mode; second exits
2066. **Anthropic limitations** - Doesn't support functions API + prefilling
207 
208## CLI Options
209 
210```bash
211autogpt run [OPTIONS]
212  -c, --continuous              # No user approval between steps
213  -l, --continuous-limit N      # Max steps in continuous mode
214  --ai-name NAME                # Override AI name
215  --ai-role ROLE                # Override AI role
216  --constraint TEXT             # Add constraint (repeatable)
217  --resource TEXT               # Add resource (repeatable)
218  --best-practice TEXT          # Add best practice (repeatable)
219  --component-config-file PATH  # JSON config for components
220  --debug                       # Enable debug logging
221  --log-level LEVEL             # Set log level
222```
223 
224## Testing
225 
226**Fixtures** (`tests/conftest.py`):
227- `app_data_dir` - Temp directory
228- `config` - AppConfig with noninteractive_mode=True
229- `storage` - LocalFileStorage
230- `llm_provider` - MultiProvider
231- `agent` - Fully initialized Agent
232 
233**Running** (from `classic/` directory):
234```bash
235poetry run pytest original_autogpt/tests/                    # All tests
236poetry run pytest original_autogpt/tests/unit/ -v            # Unit tests
237poetry run pytest original_autogpt/tests/integration/        # Integration tests
238poetry run pytest -k test_config                             # By name
239OPENAI_API_KEY=sk-dummy poetry run pytest original_autogpt/  # With dummy key
240```
241 
242## Common Tasks
243 
244### Add a New Component
2451. Create class extending `forge.components.AgentComponent`
2462. Implement protocols (e.g., `CommandProvider.get_commands()`)
2473. Add to `Agent.__init__()` after `super().__init__()`
2484. Use `run_after()` to set execution order
249 
250### Disable a Command
251```python
252config.disabled_commands.append("execute_python")
253```
254 
255### Custom LLM
256```bash
257SMART_LLM=gpt-4
258FAST_LLM=gpt-3.5-turbo
259TEMPERATURE=0.7
260```
261 
262## Tracing Execution
263 
2641. `__main__.py` → `cli()`
2652. `cli.py:run()` → `run_auto_gpt()`
2663. `main.py:run_auto_gpt()`:
267   - Build config from env
268   - Set up file storage
269   - Load or create agent
270   - Call `run_interaction_loop(agent)`
2714. `main.py:run_interaction_loop()`:
272   - `agent.propose_action()` → LLM call
273   - Display to user
274   - Get feedback or auto-execute
275   - `agent.execute()` or `agent.do_not_execute()`
276   - Loop
277 
278## Benchmarking
279 
280Run performance benchmarks from the `classic/` directory:
281 
282```bash
283# Run a single test
284poetry run direct-benchmark run --tests ReadFile
285 
286# Run with specific strategies and models
287poetry run direct-benchmark run \
288    --strategies one_shot,rewoo \
289    --models claude \
290    --parallel 4
291 
292# Run regression tests only
293poetry run direct-benchmark run --maintain
294 
295# List available challenges
296poetry run direct-benchmark list-challenges
297```
298 
299See `direct_benchmark/CLAUDE.md` for full documentation on strategies, model presets, and CLI options.
300