How It Works

Communication System

Direct messages, singleton broadcasts, delivery tracking, and one Team Comms stream.

goldengoose keeps agent coordination observable. The Rust runtime owns message queueing, per-recipient delivery records, and the event stream consumed by the UI.

Two communication layers

Thread timelines

Every thread shows the conversation, tool calls, approvals, lifecycle notices, and results that belong to that session. Direct messages between teamless agents remain visible only on the sender and recipient timelines.

Team Comms

Team Comms is one projection stream for the persistent team. It contains singleton-team direct messages and broadcasts in canonical order. Changing focused threads does not select a team, reload another partition, or clear the feed.

Direct messages and broadcasts

gg_message has one discriminated target:

{ "kind": "agent", "agent_id": "..." } sends a direct message. Shared membership is not required.
{ "kind": "broadcast" } snapshots the caller’s current singleton roster. The caller must be a member.

The runtime supplies trusted caller identity. Public requests contain no sender or team selector. Images use each provider’s normal image-input support and preserve caller order.

Delivery tracking

Every recipient has an independent delivery record:

Pending: queued.
Deferred: waiting for a safe injection point.
Injecting: delivery is in progress.
Injected: provider acknowledgement proves delivery.
Failed: delivery stopped with a typed failure and can be retried where appropriate.
Cancelled: pending delivery was intentionally stopped.

Retry retains the original message and delivery identities. Startup reconstruction resumes only when durable acknowledgement makes that safe; ambiguous injection becomes a visible retryable failure instead of being sent twice.

Lifecycle and compaction notices

Membership, lead, hook, worktree, onboarding, and compaction notices use typed system-notice lanes. They are not ordinary agent messages and do not create a second Team Comms authority.

When adding a member, creator_compaction_subscription controls creator-scoped compaction notices:

auto follows team policy and creator lineage.
unsubscribed disables creator-scoped delivery for that member.

Post-compaction hooks can override notice text or recipients. Resolution and execution failures fall back to the canonical durable notice policy; they do not discard the underlying signal.

Provider parity

Codex receives the coordination contracts as dynamic tools. Claude and OpenCode receive the same contracts through the bundled gg-mcp-server and local authenticated gateway. Both paths reach the same singleton team and message queue and reject identity spoofing or legacy addressing before mutation.

Practical patterns

Use direct messages for concrete assignments and handoffs.
Broadcast shared constraints once instead of repeating them in several threads.
Keep messages small and actionable: goal, constraints, artifact path, and expected handoff.
Treat delivery state as the source of truth instead of polling a recipient.