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## Project Overview
6 
7AutoGPT Classic is an experimental, **unsupported** project demonstrating autonomous GPT-4 operation. Dependencies will not be updated, and the codebase contains known vulnerabilities. This is preserved for educational/historical purposes.
8 
9## Repository Structure
10 
11```
12classic/
13├── pyproject.toml          # Single consolidated Poetry project
14├── poetry.lock             # Single lock file
15├── forge/
16│   └── forge/              # Core agent framework package
17├── original_autogpt/
18│   └── autogpt/            # AutoGPT agent package
19├── direct_benchmark/
20│   └── direct_benchmark/   # Benchmark harness package
21└── benchmark/              # Challenge definitions (data, not code)
22```
23 
24All packages are managed by a single `pyproject.toml` at the classic/ root.
25 
26## Common Commands
27 
28### Setup & Install
29```bash
30# Install everything from classic/ directory
31cd classic
32poetry install
33```
34 
35### Running Agents
36```bash
37# Run forge agent
38poetry run python -m forge
39 
40# Run original autogpt server
41poetry run serve --debug
42 
43# Run autogpt CLI
44poetry run autogpt
45```
46 
47Agents run on `http://localhost:8000` by default.
48 
49### Benchmarking
50```bash
51# Run benchmarks
52poetry run direct-benchmark run
53 
54# Run specific strategies and models
55poetry run direct-benchmark run \
56    --strategies one_shot,rewoo \
57    --models claude \
58    --parallel 4
59 
60# Run a single test
61poetry run direct-benchmark run --tests ReadFile
62 
63# List available commands
64poetry run direct-benchmark --help
65```
66 
67### Testing
68```bash
69poetry run pytest                              # All tests
70poetry run pytest forge/tests/                 # Forge tests only
71poetry run pytest original_autogpt/tests/      # AutoGPT tests only
72poetry run pytest -k test_name                 # Single test by name
73poetry run pytest path/to/test.py              # Specific test file
74poetry run pytest --cov                        # With coverage
75```
76 
77### Linting & Formatting
78 
79Run from the classic/ directory:
80 
81```bash
82# Format everything (recommended to run together)
83poetry run black . && poetry run isort .
84 
85# Check formatting (CI-style, no changes)
86poetry run black --check . && poetry run isort --check-only .
87 
88# Lint
89poetry run flake8        # Style linting
90 
91# Type check
92poetry run pyright       # Type checking (some errors are expected in infrastructure code)
93```
94 
95Note: Always run linters over the entire directory, not specific files, for best results.
96 
97## Architecture
98 
99### Forge (Core Framework)
100The `forge` package is the foundation that other components depend on:
101- `forge/agent/` - Agent implementation and protocols
102- `forge/llm/` - Multi-provider LLM integrations (OpenAI, Anthropic, Groq, LiteLLM)
103- `forge/components/` - Reusable agent components
104- `forge/file_storage/` - File system abstraction
105- `forge/config/` - Configuration management
106 
107### Original AutoGPT
108- `original_autogpt/autogpt/app/` - CLI application entry points
109- `original_autogpt/autogpt/agents/` - Agent implementations
110- `original_autogpt/autogpt/agent_factory/` - Agent creation logic
111 
112### Direct Benchmark
113Benchmark harness for testing agent performance:
114- `direct_benchmark/direct_benchmark/` - CLI and harness code
115- `benchmark/agbenchmark/challenges/` - Test cases organized by category (code, retrieval, data, etc.)
116- Reports generated in `direct_benchmark/reports/`
117 
118### Package Structure
119All three packages are included in a single Poetry project. Imports are fully qualified:
120- `from forge.agent.base import BaseAgent`
121- `from autogpt.agents.agent import Agent`
122- `from direct_benchmark.harness import BenchmarkHarness`
123 
124## Code Style
125 
126- Python 3.12 target
127- Line length: 88 characters (Black default)
128- Black for formatting, isort for imports (profile="black")
129- Type hints with Pyright checking
130 
131## Testing Patterns
132 
133- Async support via pytest-asyncio
134- Fixtures defined in `conftest.py` files provide: `tmp_project_root`, `storage`, `config`, `llm_provider`, `agent`
135- Tests requiring API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY) will skip if not set
136 
137## Environment Setup
138 
139Copy `.env.example` to `.env` in the relevant directory and add your API keys:
140```bash
141cp .env.example .env
142# Edit .env with your OPENAI_API_KEY, etc.
143```
144 
145## Workspaces
146 
147Agents operate within a **workspace** - a directory containing all agent data and files. The workspace root defaults to the current working directory.
148 
149### Workspace Structure
150 
151```
152{workspace}/
153├── .autogpt/
154│   ├── autogpt.yaml              # Workspace-level permissions
155│   ├── ap_server.db              # Agent Protocol database (server mode)
156│   └── agents/
157│       └── AutoGPT-{agent_id}/
158│           ├── state.json        # Agent profile, directives, action history
159│           ├── permissions.yaml  # Agent-specific permission overrides
160│           └── workspace/        # Agent's sandboxed working directory
161```
162 
163### Key Concepts
164 
165- **Multiple agents** can coexist in the same workspace (each gets its own subdirectory)
166- **File access** is sandboxed to the agent's `workspace/` directory by default
167- **State persistence** - agent state saves to `state.json` and survives across sessions
168- **Storage backends** - supports local filesystem, S3, and GCS (via `FILE_STORAGE_BACKEND` env var)
169 
170### Specifying a Workspace
171 
172```bash
173# Default: uses current directory
174cd /path/to/my/project && poetry run autogpt
175 
176# Or specify explicitly via CLI (if supported)
177poetry run autogpt --workspace /path/to/workspace
178```
179 
180## Settings Location
181 
182Configuration uses a **layered system** with three levels (in order of precedence):
183 
184### 1. Environment Variables (Global)
185 
186Loaded from `.env` file in the working directory:
187 
188```bash
189# Required
190OPENAI_API_KEY=sk-...
191 
192# Optional LLM settings
193SMART_LLM=gpt-4o                    # Model for complex reasoning
194FAST_LLM=gpt-4o-mini                # Model for simple tasks
195EMBEDDING_MODEL=text-embedding-3-small
196 
197# Optional search providers (for web search component)
198TAVILY_API_KEY=tvly-...
199SERPER_API_KEY=...
200GOOGLE_API_KEY=...
201GOOGLE_CUSTOM_SEARCH_ENGINE_ID=...
202 
203# Optional infrastructure
204LOG_LEVEL=DEBUG                     # DEBUG, INFO, WARNING, ERROR
205DATABASE_STRING=sqlite:///agent.db  # Agent Protocol database
206PORT=8000                           # Server port
207FILE_STORAGE_BACKEND=local          # local, s3, or gcs
208```
209 
210### 2. Workspace Settings (`{workspace}/.autogpt/autogpt.yaml`)
211 
212Workspace-wide permissions that apply to **all agents** in this workspace:
213 
214```yaml
215allow:
216  - read_file({workspace}/**)
217  - write_to_file({workspace}/**)
218  - list_folder({workspace}/**)
219  - web_search(*)
220
221deny:
222  - read_file(**.env)
223  - read_file(**.env.*)
224  - read_file(**.key)
225  - read_file(**.pem)
226  - execute_shell(rm -rf:*)
227  - execute_shell(sudo:*)
228```
229 
230Auto-generated with sensible defaults if missing.
231 
232### 3. Agent Settings (`{workspace}/.autogpt/agents/{id}/permissions.yaml`)
233 
234Agent-specific permission overrides:
235 
236```yaml
237allow:
238  - execute_python(*)
239  - web_search(*)
240
241deny:
242  - execute_shell(*)
243```
244 
245## Permissions
246 
247The permission system uses **pattern matching** with a **first-match-wins** evaluation order.
248 
249### Permission Check Order
250 
2511. Agent deny list → **Block**
2522. Workspace deny list → **Block**
2533. Agent allow list → **Allow**
2544. Workspace allow list → **Allow**
2555. Session denied list → **Block** (commands denied during this session)
2566. **Prompt user** → Interactive approval (if in interactive mode)
257 
258### Pattern Syntax
259 
260Format: `command_name(glob_pattern)`
261 
262| Pattern | Description |
263|---------|-------------|
264| `read_file({workspace}/**)` | Read any file in workspace (recursive) |
265| `write_to_file({workspace}/*.txt)` | Write only .txt files in workspace root |
266| `execute_shell(python:**)` | Execute Python commands only |
267| `execute_shell(git:*)` | Execute any git command |
268| `web_search(*)` | Allow all web searches |
269 
270Special tokens:
271- `{workspace}` - Replaced with actual workspace path
272- `**` - Matches any path including `/`
273- `*` - Matches any characters except `/`
274 
275### Interactive Approval Scopes
276 
277When prompted for permission, users can choose:
278 
279| Scope | Effect |
280|-------|--------|
281| **Once** | Allow this one time only (not saved) |
282| **Agent** | Always allow for this agent (saves to agent `permissions.yaml`) |
283| **Workspace** | Always allow for all agents (saves to `autogpt.yaml`) |
284| **Deny** | Deny this command (saves to appropriate deny list) |
285 
286### Default Security
287 
288Out of the box, the following are **denied by default**:
289- Reading sensitive files (`.env`, `.key`, `.pem`)
290- Destructive shell commands (`rm -rf`, `sudo`)
291- Operations outside the workspace directory
292