CheddahBot/CLAUDE.md

# CLAUDE.md

## Project Overview

CheddahBot is a personal AI assistant for Bryan's SEO/AI agency and general life. It has a two-brain architecture: a **chat brain** (OpenRouter/Ollama/LM Studio) for conversational UI, and an **execution brain** (Claude Code CLI) for autonomous tasks like press releases, file operations, and shell commands among others.

The bot polls ClickUp for tasks, maps them to skills, and auto-executes or asks permission — then reports results back to ClickUp and the chat UI.

## Coding Workflow Rules - while we are working on building/changing the code
- Before making any changes, explain WHAT you plan to change and WHY
- Wait for my approval before editing files UNLESS I TELL YOU I AM GOING AWAY FOR A BIT - then you can use your judgement but commit the code at every big change.
- After making changes, provide a brief summary of every file modified and what changed
- If you encounter a problem during implementation, STOP and explain it instead of trying to fix it silently
- Never refactor, rename, or reorganize code beyond what was explicitly asked for

## Architecture

```
Gradio UI (ui.py)
    ↓
AgentRegistry (agent_registry.py)
  ├── default agent ← AgentConfig (config.py)
  ├── writer agent
  ├── researcher agent
  └── ops agent
    ↓
Agent (agent.py) ← Memory (memory.py, 4-layer, per-agent scoping)
    ↓                ← Skills (skills.py, markdown skills with frontmatter)
LLM Adapter (llm.py)
  ├── Chat brain: OpenRouter / Ollama / LM Studio (per-agent model override)
  └── Execution brain: Claude Code CLI (subprocess)
    ↓
Tool Registry (tools/__init__.py) ← auto-discovers tools in tools/
  ├── delegate_task → execution brain
  └── delegate_to_agent → cross-agent delegation (depth-limited)
    ↓
Scheduler (scheduler.py)
  ├── Poll loop: cron-based scheduled tasks
  ├── Heartbeat: periodic checklist from HEARTBEAT.md
  └── ClickUp loop: polls ClickUp → maps to skills → executes
    ↓
NotificationBus (notifications.py) → Gradio / future Discord / Slack
```

## Commands

```bash
# Run the app
uv run python -m cheddahbot

# Run tests (124 tests)
uv run pytest

# Run tests verbose
uv run pytest -v --no-cov

# Run only integration tests (requires live ClickUp API token)
uv run pytest -m integration

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Add a dependency
uv add <package>

# Add a dev/test dependency
uv add --group test <package>
```

## Key Files

| File | Purpose |
|------|---------|
| `cheddahbot/__main__.py` | Entry point, multi-agent wiring |
| `cheddahbot/agent.py` | Core agentic loop (chat + tool execution) |
| `cheddahbot/agent_registry.py` | Multi-agent registry (named agents, default) |
| `cheddahbot/llm.py` | Two-brain LLM adapter |
| `cheddahbot/config.py` | Config + AgentConfig dataclasses |
| `cheddahbot/db.py` | SQLite persistence (WAL, thread-safe) |
| `cheddahbot/scheduler.py` | Three daemon threads: poll, heartbeat, ClickUp |
| `cheddahbot/clickup.py` | ClickUp REST API v2 client (httpx) |
| `cheddahbot/notifications.py` | UI-agnostic pub/sub notification bus |
| `cheddahbot/memory.py` | 4-layer memory with semantic search + scoping |
| `cheddahbot/router.py` | System prompt builder |
| `cheddahbot/skills.py` | Markdown skill registry (discovers skills/*.md) |
| `cheddahbot/ui.py` | Gradio web interface |
| `cheddahbot/tools/` | Tool modules (auto-discovered) |
| `cheddahbot/tools/delegate.py` | delegate_task + delegate_to_agent tools |
| `config.yaml` | Runtime configuration (incl. agents section) |
| `identity/SOUL.md` | Agent personality |
| `identity/USER.md` | User profile |
| `skills/` | Markdown skill files with YAML frontmatter |

## Conventions

- **Config precedence**: env vars > config.yaml > dataclass defaults
- **ClickUp env vars**: `CLICKUP_API_TOKEN`, `CLICKUP_WORKSPACE_ID`, `CLICKUP_SPACE_ID`
- **Tool registration**: Use the `@tool("name", "description", category="cat")` decorator in any file under `cheddahbot/tools/` — auto-discovered on startup
- **Tool context**: Tools can accept `ctx: dict | None = None` to get `config`, `db`, `agent`, `memory`, `agent_registry` injected
- **Skills**: `.md` files in `skills/` with YAML frontmatter (`name`, `description`, `tools`, `agents`). Files without frontmatter are data files (skipped by registry)
- **Multi-agent**: Configure agents in `config.yaml` under `agents:` key. Each agent has `name`, `display_name`, `model` (override), `tools` (whitelist), `memory_scope`. First agent is the default. Use `delegate_to_agent` tool for cross-agent delegation (depth limit: 3).
- **Memory scoping**: Agents with `memory_scope` set use `memory/{scope}/` subdirectory. Empty scope = shared `memory/` root. Fallback search checks both scoped and shared directories.
- **Database**: SQLite with WAL mode, thread-local connections via `threading.local()`
- **KV store**: Task state stored as JSON at `clickup:task:{id}:state` keys
- **ClickUp field mapping**: `Work Category` field (not `Task Type`) identifies task types like "Press Release", "Link Building". The `Client` field (not `Company`) holds the client name.
- **Notifications**: All scheduler events go through `NotificationBus.push()`, never directly to a UI
- **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

## ClickUp Skill Mapping

The scheduler maps ClickUp `Work Category` → tool name via `config.yaml`:

```yaml
skill_map:
  "Press Release":
    tool: "write_press_releases"
    auto_execute: true
    field_mapping:
      topic: "task_name"        # uses ClickUp task name
      company_name: "Client"    # looks up "Client" custom field
```

Task lifecycle: `to do` → discovered → approved/awaiting_approval → executing → completed/failed (+ attachments uploaded)

## Testing

Tests live in `tests/` and use pytest. All tests run offline with mocked APIs.

- `test_clickup.py` — API response parsing + HTTP client (respx mocks)
- `test_db.py` — `kv_scan` and notifications table methods
- `test_notifications.py` — NotificationBus pub/sub behavior
- `test_clickup_tools.py` — Chat tool state machine (approve/decline)
- `test_email.py` — EmailClient SMTP send + attachments (mocked)
- `test_docx_export.py` — Plain text → .docx formatting and file creation
- `test_press_advantage.py` — Press Advantage API client, company parsing, link building, submit tool
- `test_scheduler_helpers.py` — `_extract_docx_paths` regex extraction from tool output

Fixtures in `conftest.py`: `tmp_db` (fresh SQLite), `sample_clickup_task_data` (realistic API response).

## Don't

- Don't edit `.env` — it contains secrets
- Don't manually activate venvs — use `uv run`
- Don't add to `requirements.txt` — use `uv add` (pyproject.toml)
- Don't call tools directly from UI code — go through `NotificationBus` for scheduler events
- Don't store ClickUp state outside of `kv_store` — it's the single source of truth