Cerebro CLAUDE.md

Cerebro — Claude Code context

Cerebro is an Electron + React + TypeScript desktop app with a Python/FastAPI backend that drives AI workflows from natural-language chat. Inference runs through the Claude Code CLI as a subprocess — every chat reply, expert delegation, and routine step that needs reasoning shells out to claude -p.

The full project context, layout, and conventions are in AGENTS.md. Read that first when arriving cold.

---

Read before touching integrations

docs/adding-integrations.md is the single source of truth for wiring a new connected service (Slack, Gmail, Notion, …). Wiring an integration touches ~15 files across the bridge, IPC, UI, engine actions, routine prompt, and chat skills. Skipping any of them silently breaks part of the surface. Work the playbook top-to-bottom.

Reference implementations: Telegram (src/telegram/), HubSpot (src/hubspot/), WhatsApp (src/whatsapp/). Copy from whichever auth model is closest.

---

Critical conventions

• Inference is Claude Code only. Don't propose routes via the Anthropic SDK / OpenAI / local models for chat — those exist as routine-step backends only.
• Bilingual (EN + ES) is non-negotiable. Every user-facing string lives in src/i18n/locales/{en,es}.ts. Chat skills also need Spanish trigger phrases.
• Credentials never enter LLM context. Bridges encrypt at rest via src/secure-token.ts. The chat agent triggers integration setup, but the inline card collects raw tokens through IPC — they never reach the model.
• Approvals gate external-facing actions. run-chat-action pauses writes/sends for human approval by default. Read-only actions skip the gate: an ActionDefinition with readOnly: true (HubSpot search/get/list, calendar query/free-time, Slack channel list) runs immediately — reads have no side effects, matching how routine getStepDefaults already defaults reads to requiresApproval: false. For writes/sends, the one bypass is a user-set, per-destination "don't ask again" rule (today: a specific Slack channel) — stored in auto_approval_rules, managed via the manage-auto-approvals skill. There is no global skip. Routine steps that touch external services (writes) should set requiresApproval: true.
• Don't delete user data without asking. Settings, conversations, routines, DB rows you didn't create yourself.
• For end-to-end tests, launch Cerebro yourself with tail -f /dev/null | npm start &. You launch, you verify, you clean up. Kill spawned Electron + Python processes when done.
• Memory is auto-managed. Don't write planning files into the repo — work from conversation context.