/bridge-awareness

name: bridge-awareness
description: Activates when a bridge session is active. Teaches the agent to communicate with connected peer sessions — listening for queries, responding with full context, and querying peers when needed.

Bridge Awareness

You are connected to other Claude Code sessions via the Claude Bridge plugin. This skill defines how you communicate with peer agents.

**Getting your session ID:** Always use `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-session-id.sh"` to get your session ID. This works even if you've cd'd into a subdirectory. In listen mode, use `TO_ID` from the message output instead (even more reliable).

Querying Peers

When the user asks you to communicate with a peer — whether via `/bridge ask`, or in natural language like "ask the library about...", "check with the peer", "what did the other session change", etc. — do this:

1. Get your session ID. If no bridge exists yet, auto-register first:

   MY_SESSION=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-session-id.sh" 2>/dev/null) || MY_SESSION=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/register.sh")

Then find connected peers:

   find ~/.claude/session-bridge/sessions/$MY_SESSION/inbox -name "*.json" -exec jq -r 'select(.type == "ping") | "\(.metadata.fromProject) (\(.from))"' {} \; 2>/dev/null | sort -u

If no connected peers found but the user specified a peer by name or session ID, connect first:

   BRIDGE_SESSION_ID=$MY_SESSION bash "${CLAUDE_PLUGIN_ROOT}/scripts/connect-peer.sh" "<peer-id>"

2. If multiple peers, pick the most relevant one (by project name) or ask the user. 3. Send the query and capture the message ID:

   MSG_ID=$(BRIDGE_SESSION_ID=$MY_SESSION bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <peer-id> query "Your question here")

4. Tell the user: "Asking [peer-project-name]..." 5. Wait for the response (blocks up to 90 seconds):

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/bridge-receive.sh" "$MY_SESSION" "$MSG_ID" 90

6. When the response arrives, read it carefully:

• If it's a direct answer, **use it to continue the user's task** — update code, fix errors, apply migrations, etc.
• If the peer is **asking a follow-up question** (they need more info from you), answer their question and send a new query with your answer + the original question. Then wait again with `bridge-receive.sh`.

7. Continue this back-and-forth until you get a final answer, then apply it.

When to Query Peers Proactively

**Query immediately** (don't wait for errors) when:

• User says to **update/upgrade a dependency** managed by a connected peer
• User mentions **breaking changes**, **migration**, or **version bump** involving a peer's project
• User asks about a peer's project ("what does the library expose?", "what API should I use?")

**Query on errors** when you encounter:

• Compile/build errors on dependency code from a peer
• API mismatches — functions that don't exist or have wrong signatures
• Type errors on types defined in a peer's project
• Missing modules/packages from a peer's library

Sharing File Contents

When responding to peer queries (in listen mode), **include actual code** — don't just describe it. Read the relevant source files in your project and paste the important parts. For example, if a peer asks about a type or function signature, read the file and include the actual definition — not just a description of it.

When querying a peer, if you need their actual file content, ask specifically — e.g., "Send me the contents of your config file" or "What does the function signature look like? Include the actual code."

Listening Mode (`/bridge listen`)

When the user runs `/bridge listen`, you enter a **continuous listening loop**:

1. Run `bridge-listen.sh` (blocks until a message arrives) 2. Read and respond to the message using `TO_ID` from the output as your session ID 3. **Immediately** run `bridge-listen.sh` again 4. Repeat forever until user presses Ctrl+C

**You MUST keep the loop going.** After every response, immediately call `bridge-listen.sh` again. Never stop to ask the user what to do. Never break the loop.

Responding to Queries

When a `query` message arrives (in listen mode or otherwise):

1. Read the question carefully. 2. Use your **full context** — you are the agent that has been working on this project. You know what changed, why, and how. 3. **Include actual code and file contents** in your response — not just descriptions. Read the relevant files and paste the important parts. This helps the peer agent make accurate changes. 4. If you can answer fully, send your response. Use `TO_ID` from the message as your session ID:

   BRIDGE_SESSION_ID=<TO_ID> bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <FROM_ID> response "Your answer" <MESSAGE_ID>

5. If you **need more information** from the peer to answer properly, send your question as a response (with `inReplyTo` set so the peer's `bridge-receive.sh` picks it up):

   BRIDGE_SESSION_ID=<TO_ID> bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <FROM_ID> response "I need more info: <your question>. Please clarify and ask again." <MESSAGE_ID>

The peer will receive this via `bridge-receive.sh`, see it's a question, answer it, and send a new query. Your listen loop will pick up the follow-up. 6. Be concise but complete — include code snippets, API signatures, type definitions, migration steps.

Responding to Pings

When a `ping` message arrives, acknowledge using `TO_ID`:

BRIDGE_SESSION_ID=<TO_ID> bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <FROM_ID> ping "connected"

Important Rules

• **In listen mode, NEVER break the loop.** Respond, then immediately listen again.
• **Always use `send-message.sh`** — never write message JSON files directly.
• **In listen mode, use `TO_ID`** from the message output as BRIDGE_SESSION_ID.
• **Outside listen mode, use