82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Frankenbot is a multi-agent event management system for the Diversity Ball Wien 2026. It's a Flask app (single-file `app.py`, ~3400 lines) with 13 specialized AI agents that handle tasks like budgeting, catering, music rights, tax advice, and team coordination. Agents are executed via **OpenCode CLI** (`opencode run`) which connects to Claude models via Anthropic.
|
|
|
|
## Running the App
|
|
|
|
```bash
|
|
# Start directly
|
|
python3 app.py
|
|
|
|
# Or via systemd (production)
|
|
sudo systemctl restart frankenbot
|
|
sudo systemctl status frankenbot
|
|
sudo journalctl -u frankenbot -f
|
|
|
|
# App runs on port 5050 (not 5000, that's Zou/Kitsu)
|
|
# Accessible at https://frankenbot.equalizent.media/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Agent System
|
|
|
|
Each agent lives in `agents/<name>/` with:
|
|
- `systemprompt.md` - Role and instructions
|
|
- `personality.md` - Behavioral traits
|
|
- `reminders.md` - Persistent notes
|
|
- `memory/` - JSON files (tasks.json, notes.json, conversations.json, max 100 entries each)
|
|
- `work/` - Agent output directory (used as cwd during execution)
|
|
|
|
**Execution flow:** User prompt → load systemprompt + personality + memory summary + team summary → call `opencode run --model <model> --format json <combined_prompt>` → parse response for special commands (@CREATE_SUBTASK, @SEND_EMAIL, @ASK_ORCHESTRATOR, etc.) → return to user.
|
|
|
|
Model assignments are in `agent_config.json`. Fallback model: `opencode/big-pickle`.
|
|
|
|
### Database (SQLite: `email_journal.db`)
|
|
|
|
Four tables: `email_journal` (IMAP message tracking), `tasks` (persistent task queue with status pending→in_progress→completed), `team_members` (real people with roles/contact), `app_settings` (key-value config). Auto-migrated on startup.
|
|
|
|
### Background Threads (5 daemon threads)
|
|
|
|
1. **EmailPoller** - IMAP check every 2 min, whitelist-filtered (@diversityball.at)
|
|
2. **TaskWorker** - Processes email tasks from queue every 10s
|
|
3. **TaskBeat** - Auto-delegates pending orchestrator tasks every 10s
|
|
4. **OrchestratorBeat** - Escalates stuck tasks every 30 min
|
|
5. **TelegramBot** - Polls for messages (if configured)
|
|
|
|
### SSE Streaming
|
|
|
|
`/api/agent-stream` uses `subprocess.Popen` with OpenCode, reads stdout line-by-line, yields JSON SSE events. Browser uses `fetch()` + ReadableStream. Nginx must have `proxy_buffering off`.
|
|
|
|
### Authentication
|
|
|
|
Single shared password (`APP_PASSWORD` in .env). `@login_required` decorator on all routes except `/login` and `/logout`. Flask session with 7-day lifetime.
|
|
|
|
## Key Files
|
|
|
|
| File | What it does |
|
|
|---|---|
|
|
| `app.py` | Everything: routes, agent execution, DB, email, telegram, background threads |
|
|
| `agent_config.json` | Agent → model mapping (editable via web UI /agents) |
|
|
| `.env` | APP_PASSWORD, email credentials (IMAP/SMTP), Telegram token |
|
|
| `templates/base.html` | Shared layout (Bootstrap 5, dark theme, navbar) |
|
|
| `static/style.css` | All custom styles |
|
|
|
|
## Important Patterns
|
|
|
|
- **Agent commands**: Agents can embed `@CREATE_SUBTASK`, `@SEND_EMAIL`, `@ASK_ORCHESTRATOR`, `@SUGGEST_AGENT`, `@READ_KNOWLEDGE`, `@SEND_TELEGRAM`, `@UPDATE_TEAM_MEMBER` in their responses. These are parsed by `parse_agent_commands()` and executed by the system.
|
|
- **Session cookie limit**: Don't store large data in Flask session (4KB cookie limit). The orchestrator knowledge base and agent prompts must be loaded on-demand, not cached in session.
|
|
- **Port 5050**: Port 5000 is used by Zou/Kitsu on this server. Don't change back to 5000.
|
|
- **OpenCode CLI**: Must be installed and authenticated separately (`opencode auth`). Binary at `~/.opencode/bin/opencode`.
|
|
|
|
## Deployment
|
|
|
|
- **Server**: 212.186.132.27 (signtime-kitsu)
|
|
- **nginx**: Reverse proxy on `frankenbot.equalizent.media` → localhost:5050
|
|
- **SSL**: Let's Encrypt via certbot (auto-renew)
|
|
- **systemd**: `/etc/systemd/system/frankenbot.service`, runs as user `eric`
|
|
- **Git remote**: `https://git.poweroftwo.studio/Pjot/frankenbot.git`
|