Agent Context Bridge

CI Node.js >=24 License: MIT CC Switch

Maintained by @Yongthyuan.

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, local audit helpers, and encrypted local-directory sync helpers.

Project Status

• Current release line: 1.0.0.
• Runtime: Node.js >=24, Linux/WSL-first.
• Distribution: GitHub install through npx -y github:Yongthyuan/agent-context-bridge.
• Safety posture: local-first, default-deny for remote sync and native writes.
• Scope boundary: the bridge creates continuation context; it does not claim native lossless resume between different agent products.

Features

• 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.
• Stores runtime state under the current project in .agent-bridge/.
• Avoids modifying native agent session stores by default.

Install

CC Switch

Open the hosted installer:

https://yongthyuan.github.io/agent-context-bridge/cc-switch/install.html

The page generates two CC Switch deep links:

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

The generated MCP command uses:

npx -y github:Yongthyuan/agent-context-bridge bridge-mcp

CLI

Install directly from GitHub:

npm install -g github:Yongthyuan/agent-context-bridge

Initialize bridge storage in a project:

bridge detect

The first run is lightweight: it scans known session roots, creates project-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

Supported Agents

Agent	Aliases	Session handling
Claude Code	claude, claude_code	JSONL session detection and handoff rendering
Codex	codex	JSONL session detection and handoff rendering
Gemini CLI	gemini, gemini_cli	JSONL-style adapter and shell mapping
opencode	opencode	JSONL-style adapter and shell mapping
Cursor	cursor	JSONL-style adapter and terminal mapping
Aider	aider	Markdown session adapter and shell mapping

Built-in registry packs:

core
gemini-cli
opencode
cursor
aider
protocol-core

Command Reference

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>]

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

npm ci
npm test
npm run typecheck
npm pack --dry-run

In this WSL workspace, the verified commands are:

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

See ARCHITECTURE.md for the module layout, ROADMAP.md for planned direction, CONTRIBUTING.md for contribution workflow, RELEASE.md for release procedure, SECURITY.md for vulnerability reporting, and CHANGELOG.md for release notes.

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