# Agent Bridge
[](https://github.com/cote-star/agent-bridge)
**Let your AI agents talk about each other.**
Ask one agent what another is doing, and get an evidence-backed answer. No copy-pasting, no tab-switching, no guessing.
```bash
bridge read --agent claude --json
```
## Why It Exists
- **Silo Tax**: multi-agent workflows break when agents cannot verify each other's work.
- **Cold-Start Tax**: every new session re-reads the same repo from zero.
- **Visibility-first architecture**: give agents evidence + context first; add orchestration only when needed.
## How It Works
1. **Ask naturally** - "What is Claude doing?" / "Did Gemini finish the API?"
2. **Agent runs bridge** - Your agent calls `bridge read`, `bridge compare`, etc. behind the scenes.
3. **Evidence-backed answer** - Sources cited, divergences flagged, no hallucination.
**Tenets:**
- **Local-first** - reads directly from agent session logs on your machine. No data leaves.
- **Evidence-based** - every claim tracks to a specific source session file.
- **Privacy-focused** - automatically redacts API keys, tokens, and passwords.
- **Dual parity** - ships Node.js + Rust CLIs with identical output contracts.
## Demo
### The Handoff
Switch from Gemini to Claude mid-task. Claude picks up where Gemini left off.
### The Status Check
Three agents working on checkout. You ask Codex what the others are doing.
## Quick Start
### 1. Install
```bash
npm install -g agent-bridge
# or
cargo install agent-bridge
```
### 2. Setup
```bash
bridge setup
bridge doctor
```
From zero to a working skill query in under a minute:
This wires skill triggers into your agent configs (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) so agents know how to use the bridge.
### 3. Ask
Tell any agent:
> "What is Claude doing?"
> "Compare Codex and Gemini outputs."
> "Pick up where Gemini left off."
The agent runs bridge commands behind the scenes and gives you an evidence-backed answer.
### Session Selection Defaults
After `bridge setup`, provider instructions follow this behavior:
- If no session is specified, read the latest session in the current project.
- "past session" / "previous session" means one session before latest.
- "last N sessions" includes latest.
- "past N sessions" excludes latest (older N sessions).
- Ask for a session ID only if initial fetch fails or exact ID is explicitly requested.
## Context Pack
A context pack is an agent-first, token-efficient repo briefing for end-to-end understanding tasks.
Instead of re-reading the full repository on every request, agents start from `.agent-context/current/` and open project files only when needed.
This works the same for private repositories: the pack is local-first and does not require making your code public.
At a glance:
- `5` ordered docs + `manifest.json` (compact index, not a repo rewrite).
- Deterministic read order: `00` -> `10` -> `20` -> `30` -> `40`.
- Main-only smart sync: updates only when context-relevant files change.
- Local recovery snapshots with rollback support.
### Recommended Workflow
```bash
# One-shot setup (recommended for new installs)
bridge setup --context-pack
# Manual build/refresh
bridge context-pack build
# Install pre-push hook (syncs only for main pushes when relevant)
bridge context-pack install-hooks
```
Ask your agent explicitly:
> "Understand this repo end-to-end using the context pack first, then deep dive only where needed."
### Context Pack Demo
Create and wire a context pack for token-efficient repo understanding:
### Main Push Sync Policy
- Pushes that do not target `main`: skipped.
- Pushes to `main` with no context-relevant changes: skipped.
- Pushes to `main` with context-relevant changes: rebuilds pack and creates local recovery snapshot.
Optional pre-PR guard:
```bash
bridge context-pack check-freshness --base origin/main
```
### Usage Boundaries
- Do not treat context pack as a substitute for source-of-truth when changing behavior-critical code.
- Do not expect automatic updates from commits alone or non-`main` branch pushes.
- Do not put secrets in context-pack content; `.agent-context/current/` is tracked in git.
### Layered Model
- **Layer 0 (Evidence)**: cross-agent session reads with citations.
- **Layer 1 (Context)**: context-pack index for deterministic repo onboarding.
- **Layer 2 (Coordination, optional)**: explicit orchestration only when layers 0-1 are insufficient.
Recovery matrix:
- `.agent-context/current/` -> `git checkout <commit> -- .agent-context/current`
- `.agent-context/snapshots/` -> `bridge context-pack rollback`
## Supported Agents
| **Read Content** | Yes | Yes | Yes | Yes |
| **Auto-Discovery** | Yes | Yes | Yes | Yes |
| **CWD Scoping** | Yes | No | Yes | No |
| **List Sessions** | Yes | Yes | Yes | Yes |
| **Search** | Yes | Yes | Yes | Yes |
| **Comparisons** | Yes | Yes | Yes | Yes |
## How It Compares
| **Approach** | Read-only evidence layer | Full orchestration framework | Parallel agent spawning |
| **Install** | `npm i -g agent-bridge` or `cargo install` | pip + ecosystem | git clone |
| **Agents** | Codex, Claude, Gemini, Cursor | Provider-specific | Usually Claude-only |
| **Dependencies** | Zero npm prod deps | Heavy Python/TS stack | Moderate |
| **Privacy** | Local-first, auto-redaction | Cloud-optional | Varies |
| **Cold-start solution** | Context Pack (5-doc briefing) | None | None |
| **Language** | Node.js + Rust (conformance-tested) | Python or TypeScript | Single language |
| **Philosophy** | Visibility first, orchestration optional | Orchestration first | Task spawning |
## Architecture
The bridge sits between your agent and other agents' session logs. You talk to your agent - your agent talks to the bridge.
```mermaid
sequenceDiagram
participant User
participant Agent as Your Agent (Codex, Claude, etc.)
participant Bridge as bridge CLI
participant Sessions as Other Agent Sessions
User->>Agent: "What is Claude doing?"
Agent->>Bridge: bridge read --agent claude --json
Bridge->>Sessions: Scan ~/.claude/projects/*.jsonl
Sessions-->>Bridge: Raw session data
Bridge->>Bridge: Redact secrets, format
Bridge-->>Agent: Structured JSON
Agent-->>User: Evidence-backed natural language answer
```
<details><summary>Diagram not rendering? View as image</summary>
</details>
## Easter Egg
`bridge trash-talk` roasts your agents based on their session content.
## Roadmap
- **Context Pack customization** - user-defined doc structure, custom sections, team templates.
- **Windows installation** - native Windows support (currently macOS/Linux).
- **Auto-generated instruction wiring** - `bridge setup` creates/updates `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`, plus `.agent-bridge/INTENTS.md` and provider snippets.
- **Non-intrusive update notifications** - once-per-version update hints with fail-silent behavior and structured status in `bridge doctor` (`BRIDGE_SKIP_UPDATE_CHECK=1` opt-out).
- **Cross-agent context sharing** - agents share context snippets (still read-only, still local).
- **Agent-to-agent messaging** - agents leave messages for each other via bridge.
## Choose Your Path
- **I need full command syntax and JSON outputs**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
- **I need context-pack internals and policy details**: [`CONTEXT_PACK.md`](./CONTEXT_PACK.md)
- **I am contributing or extending the codebase**: [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md)
- **I need protocol and schema contract details**: [`PROTOCOL.md`](./PROTOCOL.md)
- **I need contribution process and PR expectations**: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
- **I need release-level changes and upgrade notes**: [`RELEASE_NOTES.md`](./RELEASE_NOTES.md)
---
Contributions and issue reports are welcome.