frankenbot/CLAUDE.md

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

# 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