How do I use Agent Context Bridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Agent Context Bridge prepare a handoff from my latest Codex session to Claude" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Agent Context Bridge

Agent Context Bridge is a local-first bridge for moving useful context between coding agents. It indexes nearby agent sessions, normalizes them into a shared event model, and creates concise handoff packets that another agent can continue from without pasting full raw transcripts.

It is designed to extend CC Switch as an installable Skill + MCP server. CC Switch keeps switching agents; Agent Context Bridge adds session discovery, evidence-backed handoff packets, timeline/search, policy checks, and local audit/sync helpers.

What It Does

Detects Claude Code, Codex, Gemini CLI, opencode, Cursor, and Aider session files.
Builds a normalized project timeline with raw evidence references.
Creates target-specific continuation prompts for agent handoff.
Exposes the same bridge through CLI commands, MCP tools, and a small local browser UI.
Provides CC Switch deep links for one-click Skill and MCP installation.
Keeps runtime state under the current project in .agent-bridge/.
Defaults to local-only behavior and does not mutate native agent history.

Install With CC Switch

Host this repository on GitHub Pages, then open:

https://<owner>.github.io/agent-context-bridge/cc-switch/install.html

The install page generates two CC Switch deep links:

Skill import: installs the bridge usage instructions.
MCP import: adds the bridge MCP server command.

The MCP template runs:

npx -y github:<owner>/agent-context-bridge bridge-mcp

Users only need Node.js >=24 and access to the GitHub repository.

The install pack lives in:

skills/agent-context-bridge/SKILL.md
mcp/cc-switch.mcp.json
cc-switch/install.html
cc-switch/README.md

Manual Setup

Install directly from GitHub:

npm install -g github:<owner>/agent-context-bridge

Then initialize bridge storage in a project:

bridge detect

This creates .agent-bridge/ and writes default registry mappings. The first run is intentionally lightweight: it scans known session roots, creates local state, and does not copy full native histories.

Quick Start

List known agents and sessions:

bridge agents list
bridge list --all

Create a handoff packet:

bridge handoff --from codex --to claude --latest

Search recent normalized events:

bridge timeline --limit 20
bridge search "failing test" --limit 10

Use the CC Switch compatibility layer:

bridge cc-switch manifest
bridge cc-switch sessions --target claude
bridge cc-switch handoff --session codex:<session-id> --target claude

Start the local UI:

bridge ui start --host 127.0.0.1 --port 0

Command Groups

Core handoff:

bridge detect
bridge list [--all] [--agent <agent>]
bridge open <agent>:<session-id> [--target <agent>]
bridge handoff --from <agent> --to <agent> [--latest|--session <id>]
bridge raw <agent>:<id> [--around <text>] [--tool <name>] [--since-compact]
bridge doctor

Workbench:

bridge agents list
bridge timeline [--agent <agent>] [--session <id>] [--op <canonical_op>] [--limit <n>]
bridge search <query> [--agent <agent>] [--op <canonical_op>] [--tool <name>] [--limit <n>]
bridge registry list [--available|--installed]
bridge registry validate --pack <pack>
bridge registry install <pack>
bridge hooks status [--agent <agent>]
bridge hooks plan --agent <agent>
bridge hooks install --agent <agent> --yes
bridge hooks uninstall --agent <agent> --yes
bridge memory export [--format markdown|json] [--output <path>]
bridge ui start [--host 127.0.0.1] [--port 0|<port>]

Coordination and policy:

bridge protocol inspect
bridge protocol negotiate --from <agent> --to <agent>
bridge registry negotiate --from <agent> --to <agent>
bridge policy show
bridge policy check <remote.push|remote.pull|native.write|raw.full|raw.excerpt|collab.turn> --agent <agent>
bridge team append --actor <id> --agent <agent> --summary <text> [--files a,b]
bridge team audit
bridge remote status
bridge remote push --to <dir> --key-env <ENV> [--agent <agent>] --yes
bridge remote pull --from <bundle> --key-env <ENV> [--agent <agent>] --yes
bridge collab start --agents codex,claude --mode single_driver [--owner <agent>] [--phase <phase>]
bridge collab status
bridge collab turn --owner <agent> --phase <phase> [--actor <agent>] [--summary <text>]

Supported agent aliases:

claude, claude_code, codex, gemini, gemini_cli, opencode, cursor, aider

Built-in registry packs:

core
gemini-cli
opencode
cursor
aider
protocol-core

MCP Tools

Run the MCP server with:

bridge-mcp

It exposes newline-delimited JSON-RPC stdio tools:

bridge_list_sessions
bridge_open_session
bridge_get_handoff_packet
bridge_get_raw_excerpt
bridge_get_sync_status
bridge_append_ledger_event
bridge_list_agents
bridge_get_timeline
bridge_search_events
bridge_list_registry_packs
bridge_validate_registry_pack
bridge_get_hook_status
bridge_plan_hook_install
bridge_export_project_memory
bridge_get_protocol_descriptor
bridge_negotiate_protocol
bridge_negotiate_registry
bridge_check_policy
bridge_get_team_audit
bridge_get_remote_status
bridge_get_collab_status
bridge_cc_switch_manifest
bridge_cc_switch_sessions
bridge_cc_switch_handoff

MCP responses are concise by default. Raw transcripts are exposed only through bounded raw excerpt tools.

Storage And Safety

Runtime state is project-local:

.agent-bridge/
  config.json
  ledger.jsonl
  packets/
  raw/
  registry/
    default-mappings.json
    packs/
  cache/
  exports/
  ui/
  hooks/
  team-ledger.jsonl
  remote/
  collab/
    session.json

Native agent session stores are not modified by default. Hook commands are guarded: status and plan are non-mutating, and install/uninstall require --yes. Current hook installation writes only project-local hook manifests under .agent-bridge/hooks/.

Remote sync is disabled by policy by default. Push/pull require an enabled policy, a key environment variable, an explicit local directory or bundle path, and --yes. Encrypted bundles use Node built-in AES-256-GCM and do not store plaintext payloads.

Development

This is a TypeScript ESM project for Node.js >=24.

In this WSL workspace, run verification through the local conda environment:

node --test tests/**/*.test.ts
node node_modules/typescript/bin/tsc --noEmit

Common scripts:

npm test
npm run test:unit
npm run test:scenario
npm run typecheck
npm run dev -- agents list
npm run mcp:dev

Do not commit .agent-bridge/, raw transcripts, remote sync bundles, keys, logs, or generated exports.

Agent Context Bridge

Agent Context Bridge

What It Does

Install With CC Switch

Manual Setup

Quick Start

Command Groups

MCP Tools

Storage And Safety

Development

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API