agentconnect: Instructions file for Claude Code

CLAUDE.md

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

Product behavior and user-facing invariants are documented in docs/product-conventions.md. Read it before changing how AgentConnect presents or delivers messages to users.

What this is

AgentConnect is a multi-agent platform that bridges IM platforms (Slack / Telegram / Discord) to AI coding agents (Claude, Codex) over ACP. The authoritative design lives in docs/designs/ — start with architecture.md, and use the grouped index at docs/README.md to find the rest. Design documentation and every visual asset embedded in public documentation are maintained in English. Before adding or reusing a diagram or screenshot, inspect its visible text and verify that it still matches the current architecture. Prefer diffable SVG or Mermaid source over opaque raster diagrams.

The defining architectural choice: live platform message bodies and ACP update streams stay on the daemon/relay data plane. Some admission steps and turn operations require CP control RPCs; their recovery requirements are defined in high-availability.md. Agent execution always happens inside a daemon on the data plane. Where that daemon runs is a deployment choice, not part of the invariant — self-hosted on machines the organization operates, or a member of the install's managed Kubernetes pool (Cloud), which shares one PostgreSQL data plane and launches runtimes in sandbox pods; see §3.1 of the architecture design. Platform ingress is either daemon-owned directly or forwarded by the optional relay when a stable public callback endpoint is required; the CP only orchestrates. Concretely:

• A daemon owns direct platform connections, local routing, provider API egress, and agent execution over ACP the Control Plane never sees (local IPC self-hosted; one in-cluster dial to the sandbox pod in the pool). It also accepts pre-addressed public ingress from the relay. It is a self-contained "message + agent execution unit" and keeps running established sessions during CP outages within their authority lifetimes. All member-set daemons self-fence duties at T_fence after the last confirmed renewal; see the duty lease contract.
• The optional relay terminates Slack HTTP callbacks, GitHub and GitLab webhooks, generic webhooks, and webchat, then forwards content directly to the owning daemon. It does not persist message content.
• The Control Plane does orchestration/registry/auth + serves the Web UI BFF. It stores only control-plane metadata — never message bodies, ACP session/update streams, or attachment bytes. Managed agent memory with home: control-plane is the one curated-content exception, like organization knowledge. Authorized BFF operations may proxy bounded transcript, tool-body, memory, or workspace reads and workspace writes to the owning daemon without persisting their content.
• daemon ↔ CP is a single WebSocket used primarily for control signaling (register, heartbeat, orchestration commands, telemetry). It also carries the scoped request/reply frames for those on-demand BFF operations; live platform messages and ACP update streams never use it.