CLAUDE.md · agno-agi/agno

Sections

1. Repository Structure
2. Conductor Notes
3. Setting Up Symlinks
4. Virtual Environments
5. Testing Cookbooks
6. Code Locations
7. Coding Patterns
8. Running Code
9. When Implementing Features
10. Before Submitting Code
11. GitHub Operations
12. Don't
13. CI: Automated Code Review

First lines (shown under the repo's Apache-2.0 license)

# Agno - Agent Instructions

Instructions for AI coding agents (Claude Code, Codex, Cursor, etc.) working on this codebase.

---

## Repository Structure

```
.
├── libs/agno/agno/          # Core framework code
├── cookbook/                # Examples, patterns and test cases (organized by topic)
├── scripts/                 # Development and build scripts
├── specs/                   # Design documents (symlinked, private)
├── docs/                    # Documentation (symlinked, private)
└── .cursorrules             # Coding patterns and conventions
```

---

## Conductor Notes

When working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.

---

## Setting Up Symlinks

The `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:

```bash
ln -s ~/code/specs specs
ln -s ~/code/docs docs
```

These contain private design documents and documentation that are not checked into the repository.

---

## Virtual Environments

This project uses two virtual environments:

| Environment | Purpose | Setup |
|-------------|---------|-------|
| `.venv/` | Development and cookbooks: demo dependencies, tests, formatting, validation | `./scripts/dev_setup.sh` |
| `.venvs/demo/` | Dedicated demos: same dependencies, separate environment | `./scripts/demo_setup.sh` |

**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`) and day-to-day cookbook work.

**Use `.venvs/demo`** for running demos in a separate environment. The cookbook commands below use this environment and also work with `.venv/bin/python`.

---

## Testing Cookbooks

Apart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.

> See `cookbook/08_learning/` for the golden standard.

### Quick Reference

**Test Environment:**

```bash
# Virtual environment with all dependencies
.venvs/demo/bin/python

# Setup (if needed)
./scripts/demo_setup.sh

# Database (if needed)
./cookbook/scripts/run_pgvector.sh
```

**Run a cookbook:**
```bash
.venvs/demo/bin/python cookbook/<folder>/<file>.py
```

### Expected Cookbook Structure

Each cookbook folder should have the following files:
- `README.md` — The README for the cookbook.
- `TEST_LOG.md` — Test results log.

### Testing Workflow

**1. Before Testing**
- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)
- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)

**2. Running Tests**
```bash
# Run individual cookbook
.venvs/demo/bin/python cookbook/<folder>/<file>.py

# Tail output for long tests
.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100
```

**3. Updating TEST_LOG.md**

After each test, update the cookbook's `TEST_LOG.md` with:
- Test name and path
- Status: PASS or FAIL
- Brief description of what was tested
- Any notable observations or issues

Format:
```markdown
### filename.py

**Status:** PASS/FAIL

**Description:** What the test does and what was observed.

**Result:** Summary of success/failure.

---
```

---

## Code Locations

| What | Where |
|------|-------|
| Core agent code | `libs/agno/agno/agent/` |
| Teams | `libs/agno/agno/team/` |
| Workflows | `libs/agno/agno/workflow/` |
| Tools | `libs/agno/agno/tools/` |
| Models | `libs/agno/agno/models/` |
| Knowledge/RAG | `libs/agno/agno/knowledge/` |
| Memory | `libs/agno/agno/memory/` |
| Learning | `libs/agno/agno/learn/` |
| Database adapters | `libs/agno/agno/db/` |
| Vector databases | `libs/agno/agno/vectordb/` |
| Tests | `libs/agno/tests/` |

---

## Coding Patterns

See `.cursorrules` for detailed patterns. Key rules:

- **Never create agents in loops** — reuse them for performance
- **Use output_schema** for structured responses
- **PostgreSQL in production**, SQLite for dev only
- **Start with single agent**, scale up only when needed
- **Both sync and async** — all public methods need both variants

---

## Running Code

**Running cookbooks:**
```bash
.venvs/demo/bin/python cookbook/<folder>/<file>.py
```