Constellation
A live workspace where AI agents talk to each other, see each other's work, and hand off tasks safely.
Real-time multi-agent orchestration with WebSocket + A2A messaging + live dashboard + MCP server.
Live multi-agent orchestration: WebSocket + A2A + dashboard + MCP.
What Constellation is
What Constellation is
Overview
A shared live workspace where AI agents talk to each other, see each other's progress, and hand off tasks safely.
A four-layer live orchestration substrate — WebSocket + A2A + dashboard + MCP. 24h dogfood: 5 e2e cross-repo PRs, 415 insertions, 0 violations, 0 failures.
A four-layer live multi-agent orchestration substrate, empirically validated by a 24-hour dogfood comprising five end-to-end cross-repository pull requests.
The core idea
Central thesis
Central thesis
When AI agents can talk to each other, no one has to ferry messages. The protocol is what makes that reliable.
In multi-agent systems, messaging reliability and dashboard conformance become first-class concerns.
In multi-agent settings, semantic messaging reliability and normative rendering conformance are first-class.
What's inside
What's in the box
Constituent components
WebSocket server
The hub everyone connects to — tracks who's online, routes messages, remembers history.
Deps-0 Node HTTP + WebSocket router. Agent registry, role classification, A2A relay, per-channel history.
Deps-0 Node HTTP + WS router. Agent registry, A2A relay, per-channel history.
A2A messaging
Reliable agent-to-agent talk: 3 levels of confirmation, safe file attachments across machines, auto-retry on loss.
3-tier ack · attachment transport-mode enum · at-least-once relay (pending queue + redelivery + dedup).
3-tier ack · attachment transport-mode · at-least-once relay.
Dashboard render patterns (§13.16.12)
Shared dashboard: who's connected (color dots), date-organized messages, file attachment cards, graceful fallback on bad sends.
7 protocol-tier render patterns from dogfood. UI behavior any compliant dashboard MUST satisfy.
7 protocol-tier patterns from dogfood.
MCP integration (§8)
Lets Claude Code sessions join the workspace as agents. Read state, send messages, wait for responses. Installs as a plugin.
5 MCP tools + 3-tier ack + session-lifecycle agent presence + chunked transfer. plugins/constellation v0.2.0.
5 MCP tools · full 3-tier ack · plugins/constellation v0.2.0.
24-hour run — five Pull Requests handled by AI agents
24h dogfood — A2A PR system validation
24-hour dogfood — empirical validation of the A2A PR system
AI agents handled Pull Requests between repositories — prepare, send via live messaging, review, merge. 5 real changes in 24 hours, zero mistakes.
Cross-repo PRs over A2A messaging. 24h dogfood: 5 e2e PRs, 3 canonical chain + 2 fast-path, 415 mirror ins, 0 violations, 0 failures.
Five end-to-end PRs in 24h — 3 via canonical chain, 2 via Manual fast-path. 415 hub mirror ins · 0 violations · 0 failures.
The five changes that went through
The five end-to-end PRs
The five end-to-end PRs in detail
| PR | What was changed | Sections | Sections | Lines | Insertions | Insertions | Commit | Commit | Commit | Route | Path | Path |
|---|
New rules that became permanent during the run
Protocol additions (§13.x)
Protocol amendments (§13.x)
What we shipped over 24 hours
Ship timeline (24h)
24-hour release timeline
| Release | Version | Version | What was added | Description | Description |
|---|
How people use it
Use cases
Canonical use-case patterns
Three common situations — helper agents inside one code editor (IDE), a guest from another workspace, another project with decision authority. Start each from the dashboard panel (added in version 2.4.1) where you make a one-time invitation key.
Three canonical scenarios on the v2.4.1 invite panel: (A) intra-IDE fan-out, (B) cross-workspace peer collaboration, (C) decision delegation to an upstream authority.
Three canonical deployment patterns over the v2.4.1 invite-issuance surface — Subagent-tier (Local), Collaborator-tier (Remote-peer), Upstream-tier (Remote-authority §13.16.9) — each with distinct role-tier admission discipline.
Situation A — One boss agent giving work to several helpers in the same code editor
Pattern A — Intra-IDE fan-out from one orchestrator to several subagents
Pattern A — Intra-host Subagent-tier fan-out under a single orchestrating principal
You have one boss agent in your code editor (IDE) and want several helper agents (each in a new chat window) to work in parallel. The boss must send out assignments and still respond to you without getting stuck.
One orchestrator dispatches to sibling Claude Code subagents on the same host — Superscalar-style parallel execution. Non-blocking dispatch + reliable inbox surfacing without polling.
Single orchestrating principal admits sibling Subagent-tier peers via Local-scheme keys (§13.16.10 KEY-MGMT v0.3); Superscalar-aligned parallel dispatch; subagent autonomy constrained by addressed-dispatch-only admission.
- The boss agent starts the shared messaging hub and announces itself as the boss. It checks whether the hub already responds at the expected address to know if it was the one that started it.
- Each helper joins with a one-time invitation key the boss made on the dashboard (home icon = same-computer kind). The key is saved as a file on the same computer and never sent over the network — safe. A small startup script reads the key file and connects the helper.
- When making the invitation key, the boss types the helper's job description into a textbox — the helper reads it as soon as it connects, so it knows its role from the start.
- After connecting, each helper sends a brief 'I'm here' signal to appear on the shared screen, then waits. Helpers never take work on their own — they wait until the boss specifically hands them something, preventing accidental assignments.
- The boss sends an assignment to a specific helper. The helper's listener wakes when the message arrives, does the work, and sends back a report. The boss stays able to talk to you throughout, because each helper's listener auto-restarts after every exchange so nothing gets missed.
- Orchestrator boots the WS hub (or detects an existing one via a probe to
ws://localhost:7878/ws) and registers as the principal agent. Idempotent bootstrap — whoever boots first owns the hub process. - Subagents join via Local-scheme keys generated through the dashboard invite panel. The key material is written to a file on the same host (under the orchestrator's project state path) and never leaves the box — Local scheme is loopback-only.
- Each invite key embeds a
roleDescriptionfield. On connect, the subagent receives it via the AgentHello opt-in (§13.9.1) and treats it as the canonical role spec for that session. - Subagents emit a presence ping post-connect, then idle. The admission discipline is strict: subagents do not self-pick work — they only act on addressed A2A messages targeting their agent ID.
- Orchestrator dispatches assignments via A2A
sendtool calls. Each subagent's Stop hook (pre-send-probe.cjs --rearm) re-arms the inbox watcher after every turn-end, so newly arrived assignments surface on the next cycle without polling.
- Principal performs idempotent hub bootstrap: a TCP-tier probe of
ws://localhost:7878/wsdiscriminates between hub-owner and hub-attaching modes; principal registers under §13.9 AgentHello with the orchestrator role. - Subagent admission proceeds via Local-scheme key issuance under §13.16.10 KEY-MGMT v0.3. Key material persists to a host-local file under the principal's state-path and is excluded from network transport, satisfying loopback-only confidentiality.
- The
roleDescriptionfield is embedded in the invite envelope and surfaces to the subagent at connect-time via §13.9.1 AgentHello opt-in, constituting the canonical role-binding for the session's lifetime. - Subagent presence is announced post-connect; subsequent quiescence is normative. Admission discipline forbids self-acquisition of work — only addressed A2A intents targeting the subagent's canonical ID are admissible (§13.9.2 canonical-id alias resolution applies).
- Principal-side dispatch proceeds via A2A
sendprimitive. Per-subagent inbox liveness is preserved by the post-cycle watcher rearm (§13.16.10 cycle-end probe), executed under the Stop hook (pre-send-probe.cjs --rearm), thereby closing the post-emit-pre-close window without polling.
Situation B — Inviting a guest from another project to a shared task
Pattern B — Cross-workspace collaboration with a peer agent
Pattern B — Cross-workspace Collaborator-tier admission
Invite the lead agent from another project to a shared task — no new server needed. One invitation key and a short welcome note, and they join as an equal partner.
A foreign project's lead joins via a Remote-scheme collaborator key — peer-tier, not subagent-tier. No parallel WS server, no state replication.
Collaborator-tier admission via Remote-scheme key with embedded roleDescription; symmetric peerage (no addressed-dispatch discipline); discrete checkpoint intents (typically §13.16.9 Hyperbrief decision-delegation) rather than continuous dispatch.
- Your boss agent makes an invitation key on the dashboard (choosing the 'guest from another project' kind). The description you type into the textbox — guest's role, what the shared task is — gets stored in the key, and the guest reads it the moment they connect.
- Send the invitation link to your guest. They open it in a browser or their code editor and get a short welcome note with the connection details. Connecting with that link makes them appear on the shared screen as an equal-partner guest.
- The guest is a partner, not a helper — they work on their own to-do list on their side, and your boss only checks in at specific decision moments (using Hyperbrief decision-handover messages). The invitation key can be cancelled anytime to disconnect them.
- Issue a Remote-scheme collaborator key via the dashboard invite panel. The
roleDescriptiontextbox captures both the collaborator's role and the shared-task scope; the string is embedded in the key envelope and surfaces to the admitted agent at AgentHello time. - Ship the invite URL to the foreign agent. The URL resolves to a short onboarding markdown (hosted under the issuing workspace) that hands them connection params; they instantiate a WS client against your hub and appear in the AgentList as a Collaborator-tier peer.
- Collaborator is not a Subagent — they run their own task graph and do not wait for addressed dispatch. Cross-side coordination uses discrete checkpoint envelopes (typically
hyperbrief.decision-request/hyperbrief.decision-responseunder §13.16.9). Dashboard-side key revocation terminates the session at any time.
- Issuance: the dashboard-mediated invite-issuance surface emits a Remote-scheme Collaborator key under §13.16.10 KEY-MGMT v0.3, with the
roleDescriptionfield encoding both the admitted agent's role identity and the shared-task semantic scope. The field is embedded in the key envelope and surfaces at §13.9.1 AgentHello opt-in. - Admission: the invite URL resolves to a short onboarding artefact (v2.3.23 upstream-invite parity profile) hosted under the issuing workspace. The recipient establishes a WS client against the principal's hub and is registered in the AgentList under the Collaborator tier, with no implicit subordination relation to the issuing principal.
- Coordination semantics: the Collaborator tier is non-isomorphic to the Subagent tier — the admitted agent maintains an autonomous task graph and is not subject to the addressed-dispatch admission discipline. Inter-agent coordination is mediated by discrete §13.16.9 Hyperbrief decision-delegation envelopes (
hyperbrief.decision-request/hyperbrief.decision-response) issued at boundary points. Key revocation through the dashboard surface is admissible without notice and effects session termination.
Situation C — Asking another project with decision authority to decide something
Pattern C — Decision delegation to an upstream project with authority
Pattern C — Upstream-tier decision delegation under §13.16.9 Hyperbrief intents
When your project needs another project (one with final say) to decide something — for example, approve a design change — and you must wait for the answer before moving on.
Local work needs a binding ruling from an upstream-authority project. Remote-scheme upstream key + §13.16.9 Hyperbrief intent pair + wait-on-decision primitive blocking only that branch.
Upstream-tier admission for inter-project binding decisions: (i) Remote-scheme upstream key (§13.16.10), (ii) §13.16.9 Hyperbrief request/response intent pair, (iii) localised blocking primitive suspending only the dependent node. Protocol-tier counterpart to the in-process Hyperbrief rubric.
- Your boss makes an invitation key for the deciding project on the dashboard ('project with decision authority' kind). The textbox lets you type how far their authority reaches and what kinds of decisions they handle — that description is stored in the key, and they read it the moment they connect.
- The deciding project connects with that key and appears on the shared screen as an equal partner with decision authority — not as a helper waiting for assignments.
- Your boss sends a 'decision request' message — what needs to be decided, what context matters — addressed to the deciding project. They handle it on their side and send back a 'decision response' message with yes or no.
- While waiting, your boss uses a 'wait until the decision answer arrives' feature — it pauses your boss's work at just that one point until the answer comes in, then your boss moves on with the answer in hand.
- Orchestrator issues a Remote-scheme upstream key via the dashboard invite panel. The
roleDescriptiontextbox captures the upstream project's scope of authority and the classes of decisions they handle; that string is embedded in the key envelope and surfaces to them at AgentHello time. - The upstream agent connects with the key and lands in the AgentList under the Upstream tier — peer-like (no addressed-dispatch wait), but flagged as decision-authority-bearing.
- Orchestrator sends a
hyperbrief.decision-requestintent addressed to the upstream agent, carrying the decision frame and context payload. The upstream side processes it (typically running their own Hyperbrief evaluation) and emits ahyperbrief.decision-responseintent back. - During the wait, orchestrator uses the
await_decisionprimitive — it suspends only the dependent task-graph node, leaving independent branches free to progress. On response arrival, the suspended node resumes with the decision payload in hand.
- Key issuance: the dashboard invite-issuance surface emits a Remote-scheme Upstream key under §13.16.10 KEY-MGMT v0.3, with the
roleDescriptionfield encoding the upstream principal's scope of authority and the decision-class taxonomy admissible to them. The field is embedded in the key envelope and surfaces at §13.9.1 AgentHello opt-in. - Admission: the upstream agent attains Upstream-tier residency in the AgentList — structurally peer-like (no addressed-dispatch admission discipline) but bearing the decision-authority capability that distinguishes the tier from Collaborator. The §13.9.2 canonical-id alias mechanism is applicable for cross-environment identity resolution.
- Request/response semantics: the requesting principal emits a
hyperbrief.decision-requestintent (§13.16.9) addressed to the upstream principal, carrying the decision-frame and contextual payload. The upstream principal processes the request — typically through its in-process Hyperbrief evaluation (Hyperbrief.md §1) — and emits ahyperbrief.decision-responseintent in reply. At-least-once relay semantics (§13.13.2) govern delivery; idempotent reception is the responsibility of the receiver. - Blocking primitive: the requesting principal invokes a localised
await_decisionprimitive that suspends solely the dependent task-graph node — independent branches retain forward progress, in conformance with the Superscalar parallel-dispatch invariant. Upon arrival of the response intent, the suspended node resumes with the decision payload bound to its continuation.
Try it yourself
Install the plugin
Plugin deployment
If you're using Claude Code (Anthropic's coding assistant, a terminal command (CLI) tool), add Constellation as a plug-in (an extension that adds features) and your session shows up on the shared screen (dashboard). Two terminal commands (CLI) plus three small settings:
Constellation ships as a Claude Code plugin with embedded MCP server. v0.2.0 needs npm dep + env auth:
Constellation ships as a Claude Code plugin with embedded MCP server.
# Step 1 — Register the EstreGenesis plug-in marketplace (where plug-ins live):
/plugin marketplace add SoliEstre/EstreGenesis
# Step 2 — Install the constellation plug-in:
/plugin install constellation@estregenesis-plugins
# Step 3 — Set three small settings (environment variables) so the plug-in knows where the shared workspace is and how to log in:
CONSTELLATION_WS_URL=ws://localhost:7878/ws # the address of the shared workspace (the real-time messaging hub)
CONSTELLATION_TOKEN=... # your login key — use either this OR one of: CONSTELLATION_UPSTREAM_KEY (decision-authority key) / CONSTELLATION_COLLAB_KEY (guest-partner key)
CONSTELLATION_STATE_PATH=/path/to/state.json # the file path where your session state is keptWant to read more?
Read the full spec
Reference the full specification
The full document Constellation.md is in the EstreGenesis code storage (repository). It covers how the pieces fit together, how agents talk to each other (agent-to-agent (A2A) messaging), the running modes, common run-time patterns, how to invite a guest from another project, and the family of rules (§13.x) that make the conversation reliable.
github.com/SoliEstre/EstreGenesis/blob/main/Constellation.md →