🏢 Agent Office — the Sims for your Claude Code sessions

Una oficina isométrica en vivo donde tus sesiones reales de Claude Code aparecen como robots que trabajan, piensan, te avisan y se relacionan. Sin frameworks, sin build: un index.html (canvas) + un serve.py (stdlib).

Inspirado en el "Sims for managing AI agents" de Axial Studio, y en la onda de claude-squad / vibe-kanban.

✨ Qué hace

• ⚡ Sesiones reales: detecta tus sesiones de Claude Code (transcripts en ~/.claude/projects + procesos claude vivos) y las pinta como robots con nombre intuitivo (tu primer prompt) y color propio. Los subagentes aparecen enlazados a su sesión madre.
• 🗨️ Bocadillos con la verdad: el comando exacto que ejecutan, el archivo que editan (con −/+ líneas), lo que están escribiendo, o gerundios estilo spinner ("gesticulando…") cuando piensan.
• 🎮 Menú estilo Sims: click en un robot → pedirle algo (claude -p --resume), pedir resumen, compartir su contexto con otra sesión, aprobar/resolver avisos, despedir.
• 🔔 Hooks: con hooks-example.json en tu settings.json, los robots levantan bocadillo clickable cuando Claude pide permiso (Notification) o termina de responder (Stop).
• 🧠 Memoria: diario persistente de eventos (office-memory.jsonl) y un perfil de cómo trabajas escrito por Claude a partir del diario (vista Panel).
• 🧩 Squad multiagente: das un objetivo grande → un planificador lo divide → N agentes Claude reales trabajan en paralelo (los ves entrar a la oficina) → un sintetizador junta los resultados. Todo desde la UI.
• 4 vistas: Office (isométrica, con ciclo día/noche real en la ventana), Panel (dashboard por agente + squad + perfil), Graph (red de nodos por actividad), Kanban (tarjetas por tarea).

🏗️ Cómo funciona

terminales claude ──┐                       ┌── Office (canvas isométrico)
transcripts JSONL ──┼── serve.py ── SSE ────┼── Panel / Graph / Kanban
procesos (pgrep) ───┤   (caché 1.5s)        └── MEMORIA + perfil
hooks (push) ───────┘        │
                             └── claude -p / --resume  (launch · ask · share · squad)

Detección híbrida: transcripts (~/.claude/projects/**/*.jsonl) para la actividad, procesos para saber qué sigue abierto, hooks para avisos instantáneos.

🚀 Uso

python3 serve.py          # → http://localhost:8741

Abre la web mientras usas Claude Code en tus terminales y mira la oficina cobrar vida. El botón Launch Agent lanza sesiones reales headless (claude -p) o bots de simulación.

⚙️ Configuración (variables de entorno)

serve.py se configura por entorno; todas tienen valor por defecto, así que python3 serve.py funciona sin configurar nada.

Variable	Por defecto	Qué hace
AGENT_OFFICE_HOST	127.0.0.1	Interfaz donde escucha el servidor. Solo local por seguridad (no hay autenticación; ver CONTRIBUTING.md).
AGENT_OFFICE_PORT	8741	Puerto HTTP.
AGENT_OFFICE_MAX_SSE	20	Máximo de conexiones SSE (/events) concurrentes; al superarlo se rechazan nuevas.
AGENT_OFFICE_RATE_WINDOW	3	Segundos mínimos entre acciones que lanzan claude (/launch, /ask); rate-limit básico.

# Ejemplo: otro puerto y más conexiones SSE
AGENT_OFFICE_PORT=9000 AGENT_OFFICE_MAX_SSE=40 python3 serve.py

🔌 Endpoints

GET /events (SSE, estado de sesiones) · GET /memory · GET /profile · POST /launch {prompt} · POST /ask {session,prompt} · POST /share {from,to} · POST /profile · POST /hook (para los hooks de Claude Code)

📁 Archivos

• index.html — toda la UI (canvas isométrico, dashboard, grafo, kanban, menú Sims)
• serve.py — escáner de sesiones con caché + API (solo stdlib)
• hooks-example.json — snippet para conectar los hooks de Claude Code

🧪 Tests

El proyecto es deliberadamente ligero y sin dependencias, así que la verificación es la misma que corre CI: comprobar que serve.py compila limpio.

python3 -m py_compile serve.py   # debe terminar sin salida ni error

CI ejecuta exactamente este comando en cada push y pull request (ver .github/workflows/ci.yml). Si compila, el código es sintácticamente válido. Para una prueba funcional rápida, arranca el servidor y comprueba que responde:

python3 serve.py &
curl -s http://localhost:8741/memory     # debe devolver JSON (lista, posiblemente vacía)

🩺 Troubleshooting

serve.py no arranca

• Address already in use: el puerto 8741 está ocupado (¿otra instancia corriendo?). Usa otro puerto: AGENT_OFFICE_PORT=9000 python3 serve.py, o libera el que esté en uso.
• python3: command not found o errores de sintaxis: requiere Python 3.9+ (python3 --version). El servidor solo usa la stdlib; no hace falta instalar nada.
• Comprueba primero que compila: python3 -m py_compile serve.py.

No aparecen sesiones

• Agent Office detecta sesiones de dos formas: los transcripts en ~/.claude/projects/**/*.jsonl y los procesos claude vivos (vía pgrep -x claude). Si no ves robots:
  • Asegúrate de haber usado Claude Code alguna vez (debe existir ~/.claude/projects con archivos .jsonl).
  • Para ver sesiones vivas, ten una terminal con claude abierta; pgrep debe encontrar el proceso (pgrep -x claude). En algunos sistemas el binario puede tener otro nombre.
  • El escaneo está cacheado (~1.5 s) y pgrep (~5 s): espera unos segundos a que refresque.
  • La UI consume GET /events por SSE: si superas AGENT_OFFICE_MAX_SSE conexiones (varias pestañas abiertas), las nuevas se rechazan. Cierra pestañas o sube el límite.

Transcripts corruptos

• serve.py es tolerante a fallos: las líneas .jsonl mal formadas se ignoran silenciosamente y el resto se procesa igual, así que un transcript a medio escribir no rompe la oficina.
• Si una sesión concreta no aparece o sale incompleta, revisa su archivo en ~/.claude/projects/<proyecto>/<session_id>.jsonl; cada línea debe ser un objeto JSON válido.
• Los datos locales del propio Agent Office (office-memory.jsonl) también toleran líneas corruptas (se saltan). Si quieres empezar de cero, puedes borrar ese archivo: se regenera solo.

Las acciones (Launch / Ask / Squad) no hacen nada

• Requieren el CLI claude en el PATH del proceso que corre serve.py.
• Hay un rate-limit: solo se permite una acción que lance claude cada AGENT_OFFICE_RATE_WINDOW segundos (3 por defecto). Si pulsas muy rápido, espera y reintenta.