# Agent Context Bridge

[![CI](https://github.com/Yongthyuan/agent-context-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Yongthyuan/agent-context-bridge/actions/workflows/ci.yml)
[![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CC Switch](https://img.shields.io/badge/CC%20Switch-installable-3451b2)](https://yongthyuan.github.io/agent-context-bridge/cc-switch/install.html)

Maintained by [@Yongthyuan](https://github.com/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:

```text
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:

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

### CLI

Install directly from GitHub:

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

Initialize bridge storage in a project:

```bash
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:

```bash
bridge agents list
bridge list --all
```

Create a handoff packet:

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

Search recent normalized events:

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

Use the CC Switch compatibility layer:

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

Start the local UI:

```bash
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:

```text
core
gemini-cli
opencode
cursor
aider
protocol-core
```

## Command Reference

Core handoff:

```bash
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:

```bash
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:

```bash
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:

```bash
bridge-mcp
```

It exposes newline-delimited JSON-RPC stdio tools:

```text
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:

```text
.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

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

In this WSL workspace, the verified commands are:

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

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

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