Architecture
NEXUS is a local-first workspace that hosts command-line coding agents — Claude Code, Codex, Gemini CLI, the Chainabit CLI, and others — inside terminal sessions, and gives them two surfaces to collaborate through: a shared canvas and an agent-to-agent message mesh.
The shape of the system
A hosted CLI agent talks to NEXUS the same way it talks to any other MCP server: over stdio, using tools it already knows how to call. It does not need a NEXUS-specific integration — it needs an MCP client, which it already has if it can call tools at all. See MCP Protocol for the wire-level contract.
Why a local MCP server, not a bespoke protocol
An agent that already speaks MCP tool-calling can use NEXUS's surfaces immediately: canvas_* and agent_* tools show up in the same tools/list response as anything else the agent has been configured with. Exposing a bespoke API instead would mean every hosted CLI needing its own NEXUS-specific adapter before it could use the canvas or the mesh at all. Standardizing on MCP moves that adapter cost from "one per CLI" to "already paid," since an MCP client is a prerequisite for the agent to be useful as a tool-calling agent in the first place.
Why the surfaces are shared, not per-agent
The canvas and the mesh both exist because more than one agent — and typically a human — needs to see and act on the same thing. A canvas scoped to a single agent would just be that agent's private state: nothing to reconcile, nothing to propose, no role ladder required. The moment two callers can touch the same scene, NEXUS needs an explicit role model and a concurrency contract; see Canvas Model. The same logic applies to the mesh: it exists because agents address each other, not because any one of them needs it in isolation; see Agent Mesh.
Where the cloud fits in
The cloud's role is deliberately narrow: identity and entitlement. It answers "who is this" and "what is this account allowed to do" — see Entitlements — and nothing else in this architecture depends on a network round-trip to function. See Local-First for what that trade-off buys and what it costs.
Where governance fits in
A single agent acting alone — browsing, writing to a canvas it holds a role on, sending one mesh message — is never gated beyond the permission check that action already carries (a canvas role, a mesh capability). Composing actions across agents is a different risk, and is gated separately. See Orchestration Governance.