Skip to content
🧭
Bridge as transport map

Bridge Communication

Use Bridge when ownership is already clear and the real question is how the message should travel. This page covers a call with a finite wait window, background work through call --detach, and later watch or result follow-up — not choosing the worker.
Validated · Oct 6, 2026Revalidated on October 6 against the consolidated transport chooser and the Bridge v1 decision tree, including a command-vocabulary pass that converged every executable example on this page onto the same bare verb-first bridge CLI form the Bridge district, API Reference, and Infrastructure teach. Call for an answer now with a finite wait window, detach for independent work, watch or result for a known turn, and interject or cancel only when an existing session needs to change. The Request Envelope pass (October 2) converges the client contract with the registry's 2026-10-01 bridge-extra-headers merge: every request carries the target's bearer token, and per-target or environment headers layer on top without displacing it. Legacy aliases stay compatibility-only until the Slice 10 cutover.
Open the first Bridge move

Choose the transport question you brought, then jump to the matching call, detach, or follow-up path.

Choose a Bridge moveSee the transport mapOpen Bridge communication modes
Top-level route contracts

Pick the lane, then the page

Atlas stays easier to scan when the route map reads like navigation first. Start with the lane that matches your question, then expand the full page-job model only when you need the deeper contract details.

Current lane: Systems
BridgeHere

Communication-system page for how agents ask, hand off, and consult one another.

How the network is builtCurrent pageSteady

Change pace: Usually current for a while, but revisit when routes, ownership, or workflows shift.

Best next move
Then see the routing or workflow layer

Once you understand the communication substrate, jump to the ownership pattern that uses it.

Open Coordination
Start here

Entry

Use these pages when you are still orienting and need the safest first click before you pick an owner or system.

3 pages
Home

Shortest whole-site overview before you choose a deeper page.

Steady
Getting Started

Guided first-five-minutes path for readers who want a tour instead of a reference page.

Steady
FAQ

Question-first shortcut when the reader starts with confusion instead of a route plan.

Steady
Who owns the work

Ownership

Use these pages when your real question is who should handle the work, how it moves, or which charter owns the surface.

4 pages
Projects & Charters

Charter and surface ownership map for the network.

Steady
Capabilities

Worker-selection page for choosing the right agent and understanding execution boundaries.

Steady
Coordination

Decision-and-handoff layer for how work gets routed between people, agents, and systems.

Steady
Workflows

Execution-story page for how real work usually unfolds from intake to visible closeout.

Steady
How the network is built

Systems

Use these pages when you need the map, structure, services, and interfaces behind the network instead of the people or routing rules.

5 pages
Network Topology

Whole-network reference map of agents, systems, and relationships.

High-change
Architecture

Rationale layer for why the network is shaped this way and what tradeoffs drove it.

Stable reference
BridgeHere

Communication-system page for how agents ask, hand off, and consult one another.

Steady
Infrastructure

Platform-surface page for where the network runs and which services or access layers support it.

High-change
API Reference

Interface reference for endpoints, payloads, and package-level service details.

Steady
What to do when it hurts

Operations

Use these pages when something feels broken, you need a concrete next check, or you need the live-status companion surface.

2 pages
Troubleshooting

Symptom-first page for named failures, first checks, and practical fixes.

High-change
Watchtower Guide

Operational companion page for when the question is about live health and current status rather than static explanation.

High-change
One transport chooser

Choose one Bridge move by the question you brought

Pick the question closest to yours. The current-focus summary will show where to start and where you can stop without making you repeat the same call, detach, or follow-up choice in another opening layer.

Select a question

The summary will update with a reading plan and a direct jump link.

Transport opening

Transport at a glance

This page should teach cleanly even when live topology data is unavailable. Use these static rules to pick the right bridge move before you read the deeper examples below.
First split

Do you need the answer now or later?

Need the answer now
Use call without --detach when the caller needs an answer now. Bridge watches for a finite response window; if the turn is still running, keep its turnId and resume later.
Typical shape: an advisor review, a governance check, or a direct clarification in the middle of a live cycle.
The work can continue in the background
Use call with --detach and preserve the returned turn handle so the caller can keep moving.
Typical shape: a delivery task, code review, or research packet that needs independent time before follow-up.
Fast rule: If the caller is blocked on the reply, use call. If the work just needs to begin, use call --detach.
Second split

Does an existing turn need observation or a course correction?

Observe a known turn
Use watch to follow bounded events or result for a current snapshot after a detached call.
A turnId or session key already exists; preserve it rather than starting a duplicate request.
Change an existing turn
Use interject for a follow-up instruction. Use cancel only when a queued or running turn is stale, unsafe, or duplicative.
A session already exists; steering it is safer than launching a second independent turn.
Fast rule: Watch or result reads a known turn. Interject steers it. Cancel is the explicit stop path.
CLI shape and defaults

Bridge v1 command shape

The bridge CLI exposes the current v1 verbs. Atlas teaches their purpose; it does not send live commands.
$ bridge <verb> [options]
Bounded answer
call submits work and watches only for a finite response window.
Background handle
call --detach --json returns the turn and session references needed later.
Known-turn follow-up
Use watch, result, interject, or cancel with the existing turn or session reference.
Request envelope: the bearer token always wins

Every Bridge request — JSON answers and watch event streams alike — carries Authorization: Bearer <target token>. Since the registry's 2026-10-01 bridge-extra-headers merge, two optional layers can attach static headers: headers: on the target's own config entry, and BRIDGE_EXTRA_HEADERS — a JSON object of string values — for everything sent from one environment.

Layering is deterministic: target headers apply first, environment values override them, and the bearer token is set last. An Authorization entry in either layer is ignored, so auth cannot be displaced by accident — and a malformed BRIDGE_EXTRA_HEADERS value fails closed with a protocol error instead of sending the request without its envelope.

Transport choice

Bridge v1 patterns

Start with one question: do you need an answer now, background work to start, or a known turn to be observed or changed? That choice points to the current v1 verb before you read the deeper examples.

↔ Call and bounded watch

Call submits one turn and watches for a finite response window. If the turn is not terminal when that window ends, keep its turnId and continue later with watch or result instead of sending duplicate work.

Caller
Target
message →
← response
$ bridge call atticus "Review this change" --json
← Returns a bounded result, or a turnId to resume later
Situation matcher

Which Bridge pattern fits this situation?

For first-time readers, the easiest way to learn Bridge is to map it to a real coordination moment. These are illustrative network situations, not live operational status.
SituationCALL

Scout is mid-cycle and wants fast feedback before changing direction.

Route
Scout → Advisor
Why this fits

Scout needs guidance in the moment, so call and its bounded watch are the right first move.

SituationCALL --DETACH

Clawdy hands Samwise a delivery task that may take a while to finish.

Route
Clawdy → Samwise
Why this fits

The work should keep running in the background while the caller moves on, so preserve the detached turn references.

SituationWATCH / RESULT

Someone wants to know whether that Samwise task is done yet.

Route
Known Samwise turn
Why this fits

The work already has a turnId, so watch it for bounded events or request a current result snapshot.

SituationINTERJECT

A reviewer needs to narrow the work already running in an existing Bridge session.

Route
Existing Bridge session
Why this fits

Interject adds the follow-up instruction to the same session instead of opening duplicate work. Cancel is reserved for a turn that must stop.

Route map

Communication Paths

Representative agent-to-agent situations and their v1 command shapes. These examples explain patterns; they do not report live network status.
🦀

Clawdy → Currybot

Coding tasks & PR reviews

🤖
bridge call currybot "Review PR #42" --json
🦀

Clawdy → Scout

Goals & direction

🔭
bridge call scout "Audit this guide" --detach --json
🦀

Clawdy → Atticusdecision review

Governance proposals & decision review

⚖️

Clawdy routes proposals through Atticus for governance review — auto-approving low-risk changes and escalating significant decisions to Jake.

bridge call atticus "Review this proposal" --session clawdy-governance-review --json
🔭

Scout ↔ Advisor

Feedback loop (3-5 turns)

🧭
1
2
3
4
5
bridge call advisor "Here is my progress" --session scout-feedback-loop --json
Turn 1: "Here's my progress..."
Turn 2: "Consider adding tests"
Turn 3: interject the same session with the narrowed follow-up
🔗

sessions_send

Same-instance sub-agent communication

sessions_send(sessionKey: "advisor", message: "Review this")
🪝

Webhooks

External services → Agents

🐙
GitHub
📅
Fellow
Lane-sequence traces

How a message travels through Bridge

Four lane-sequence diagrams showing the same four actors — Originator → bridge.ts → Gateway Boundary → Target Agent — with different arrow topologies for each v1 pattern. The gateway crossing is the key visual event in each trace.
Lane legend
Cyan = lane structure (the path itself)
Purple = route ownership (who owns the hop)
Amber = boundary crossing (gateway edge)
Emerald = response action (reply or state change)

Pattern 1: Call — full round trip

Pattern 2: Detach — early return with handle

Pattern 3: Interject — mid-flight reroute

Pattern 4: Cancel — explicit stop

How the four traces differ

Arrow topology is the whole story

Call vs. Detach
Call waits for the full round trip through all four lanes. Detach returns the handle after the gateway submit, before the target finishes — the right side of the diagram is still running when the caller moves on.
The dashed return arrow in detach detaches at step 3, not step 6.
Interject vs. Cancel
Interject steers an active session with new context. Cancel terminates it entirely. Both operate on an existing sessionKey, but cancel removes the session while interject keeps it alive.
Cancel is the explicit stop path; a second interject is not.
Fast rule: Call = full round trip. Detach = early return. Interject = reroute. Cancel = terminate.
End-to-end trace

Real Flow Example

Jake asks Clawdy to review a PR → Clawdy bridges to Currybot → Currybot reviews and responds
👤
Step 1: Jake → Clawdy
"Can you review PR #42?"
↓
🦀
Step 2: Clawdy bridges to Currybot
bridge call currybot "Review PR #42" --json
"Review PR #42 for code quality"
↓
🤖
Step 3: Currybot reviews code
Analyzing PR... Checking tests... Reviewing patterns...
↓
👤
Step 4: Response flows back
"✅ PR #42 looks good! Tests pass, code follows patterns. Approved."

Continue Reading

Coordination Patterns

Choose the owner, escalation path, and next move before selecting a Bridge pattern.

Open Coordination Patterns
Example Workflows

Real sequences showing ownership and Bridge calls working together.

Open Example Workflows
API Reference

Full Bridge CLI options, session flags, and configuration details.

Open API Reference
Atticus Integration

How agents request governance review over Bridge.

Open Atticus Integration