# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Run Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Run the bot (requires .env with DISCORD_TOKEN and AI provider key)
python -m daemon_boyfriend

# Run with Docker
docker-compose up -d

# Syntax check all Python files
python -m py_compile src/daemon_boyfriend/**/*.py
```

## Architecture

This is a Discord bot with AI chat (multi-provider) and SearXNG web search.

### Provider Pattern
The AI system uses a provider abstraction pattern:
- `services/providers/base.py` defines `AIProvider` abstract class with `generate()` method
- `services/providers/openai.py`, `openrouter.py`, `anthropic.py` implement the interface
- `services/ai_service.py` is the factory that creates the correct provider based on `AI_PROVIDER` env var
- OpenRouter uses OpenAI's client with a different base URL

### Cog System
Discord commands are organized as cogs in `cogs/`:
- `ai_chat.py` - `/chat` command and `@mention` handler (primary user interaction)
- `search.py` - `/search` and `/image` commands using SearXNG
- `admin.py` - `/status`, `/help`, `/ping`, `/provider` commands

Cogs are auto-loaded by `bot.py` from the `cogs/` directory.

### Configuration
All config flows through `config.py` using pydantic-settings. The `settings` singleton is created at module load, so env vars must be set before importing.

### Key Design Decisions
- `ConversationManager` stores per-user chat history in memory with configurable max length
- `RateLimiter` tracks per-user rate limits using timestamps in a dict
- Long AI responses are split via `split_message()` in `ai_chat.py` to respect Discord's 2000 char limit
- The bot responds to @mentions via `on_message` listener, not just slash commands

## Environment Variables

Required: `DISCORD_TOKEN`, plus one of `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, or `ANTHROPIC_API_KEY` depending on `AI_PROVIDER` setting.

Set `DISCORD_GUILD_ID` for instant slash command sync during development (otherwise global sync takes up to 1 hour).