From c311ae5909ce6ea51658aa289947670279f3db21 Mon Sep 17 00:00:00 2001 From: PeninsulaInd Date: Tue, 17 Feb 2026 10:33:43 -0600 Subject: [PATCH] Add Multi-Agent Configuration reference to CLAUDE.md Comprehensive section covering AgentConfig fields, how to add a new agent, how agents interact (delegation, execution brain, memory scoping), and key files reference. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index b7a3e0f..ca63cc1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,6 +110,60 @@ uv add --group test - **Tests**: Use `respx` to mock httpx calls, `tmp_db` fixture for isolated SQLite instances - **ClickUp attachments**: `ClickUpClient.upload_attachment()` uses module-level `httpx.post()` (not the shared client) for multipart uploads +## Multi-Agent Configuration + +Agents are defined in `config.yaml` under the `agents:` key. Each entry creates an `AgentConfig` (see `cheddahbot/config.py`). The first agent is always the default — used by the scheduler, heartbeat, and UI. + +**If you omit the `agents:` section entirely, CheddahBot runs in single-agent mode (backward compatible).** + +### AgentConfig fields + +| Field | Type | Default | What it does | +|-------|------|---------|-------------| +| `name` | str | `"default"` | Internal ID, used for delegation and registry lookup | +| `display_name` | str | `"CheddahBot"` | Human-readable name shown in logs/UI | +| `personality_file` | str | `""` | Path to a SOUL-like `.md` file. Empty = use `identity/SOUL.md` | +| `model` | str | `""` | Chat brain model override. Empty = use global `chat_model` | +| `tools` | list/null | `null` | Tool whitelist. `null` = all tools, `[]` = no tools, `["tool1"]` = only those | +| `skills` | list/null | `null` | Skill filter. `null` = auto (skills matching agent name) | +| `memory_scope` | str | `""` | Memory namespace. Empty = shared `memory/` root. Set to e.g. `"research"` to use `memory/research/` | + +### Adding a new agent + +1. Add an entry to `config.yaml`: +```yaml +agents: + # ... existing agents ... + - name: myagent + display_name: My Agent + personality_file: "identity/MYAGENT.md" # optional + model: "" # or override e.g. "anthropic/claude-sonnet-4.5" + tools: [web_search, delegate_task, remember, search_memory] + memory_scope: "" # "" = shared, "myagent" = isolated +``` + +2. (Optional) Create a personality file at the path you specified — same format as `identity/SOUL.md`. + +3. Restart the app. Agents are wired at startup in `__main__.py` and cannot be hot-reloaded. + +### How agents interact + +- **All agents share** the same ToolRegistry and SkillRegistry (singletons). Tool whitelists just filter what each agent *sees*. +- **Cross-agent delegation**: Any agent can call `delegate_to_agent("researcher", "find X")` to route work to another agent. Max depth: 3 (prevents infinite loops). +- **Execution brain**: Any agent can call `delegate_task("do X")` to drop work to the Claude Code CLI subprocess. This is the "doer" — it has Bash, Read, Edit, Write, Glob, Grep. +- **Memory**: Agents with the same `memory_scope` (or empty) share memory. Set a unique scope to isolate an agent's long-term memory and daily logs. + +### Key files + +| File | Role | +|------|------| +| `config.yaml` (agents section) | Defines which agents exist and their config | +| `cheddahbot/config.py` (`AgentConfig`) | Dataclass defining agent fields | +| `cheddahbot/agent.py` (`Agent`) | Agent instance — conversation loop, tool calls | +| `cheddahbot/agent_registry.py` | Registry holding all agents by name | +| `cheddahbot/__main__.py` | Startup — loops over config, creates and wires agents | +| `cheddahbot/tools/delegate.py` | `delegate_task` + `delegate_to_agent` tools | + ## ClickUp Skill Mapping The scheduler maps ClickUp `Work Category` → tool name via `config.yaml`: