Context Bridge (cb)

Bridge coding context between AI agents. Seamlessly transfer session history, decisions, file modifications, and conversation context from one AI coding assistant to another.

Why?

When you switch between AI coding tools mid-task (Claude Code → Gemini, Aider → Claude, etc.), you lose all the context the previous agent built up. Context Bridge captures that context, compresses it into a token-efficient handoff prompt, and delivers it to your next agent.

Supported Agents

| Agent | Status | History Location | |-------|--------|-----------------| | Claude Code | ✅ Full | ~/.claude/projects/ | | Gemini CLI | ✅ Full | ~/.gemini/ | | Aider | ✅ Full | .aider.chat.history.md | | OpenCode | ✅ Full | ~/.local/share/opencode/ | | Cursor | 🔜 Placeholder | — | | Windsurf | 🔜 Placeholder | — |

Installation

# Clone the repo
git clone https://github.com/your-username/context-bridge.git
cd context-bridge

# Install dependencies
npm install

# Build
npm run build

# Link globally (makes `cb` available anywhere)
npm link

From npm (once published)

npm install -g context-bridge

Quick Start

# Run interactive setup (auto-detects agents, sets defaults)
cb init

# Or set up a global config (applies to all projects)
cb init --global

This walks you through choosing your default output mode, token budget, and shorthand aliases — then writes .cbrc.json so you never have to configure per-project.

Usage

Scan for agent histories

cb list
cb list -p /path/to/project

Shows which agents have session history in the current project and how many sessions exist.

Capture a session

# Capture latest Claude session
cb capture claude

# Capture a specific session and save to file
cb capture gemini -s session-id -o context.json

Outputs the full StandardCodingContext (decisions, files modified, errors, conversation history).

Bridge context between agents

# Bridge Claude → Gemini (output to stdout)
cb bridge --from claude --to gemini

# Bridge to clipboard for easy pasting
cb bridge --from aider --to claude -o clipboard

# Save to file
cb bridge --from gemini --to aider -o file -f handoff.md

# Preview without saving (dry run)
cb bridge --from claude --to gemini --dry-run

# Custom token budget
cb bridge --from claude --to gemini -t 8000

Configuration

Create a .cbrc.json in your project root or home directory:

{
  "defaultMaxTokens": 6000,
  "defaultOutput": "clipboard",
  "defaultOutputPath": ".context_bridge.md",
  "aliases": {
    "c": "claude",
    "g": "gemini",
    "a": "aider"
  }
}

Config is loaded from (first match wins):

1. <project>/.cbrc.json
2. <project>/.context-bridge.json
3. ~/.cbrc.json

With aliases configured, you can use shorthand:

cb bridge --from c --to g

CLI Reference

cb init [-g] [-p path]                    Interactive setup, writes .cbrc.json
  -g, --global              Write to ~/.cbrc.json (all projects)
  -p, --path <path>         Project path (default: cwd)

cb list [-p path]                         Scan for agent histories

cb capture <agent> [-p path] [-s id] [-o file]   Capture session context

cb bridge --from <agent> --to <agent>     Bridge context between agents
  -p, --path <path>       Project path (default: cwd)
  -s, --session <id>      Specific session ID
  -t, --max-tokens <n>    Max tokens for output (default: 4000)
  -o, --output <mode>     clipboard | file | stdout (default: stdout)
  -f, --file <path>       Output file path (default: .context_bridge.md)
  --dry-run               Preview output without copying/saving

How It Works

1. Detect — Adapter scans known locations for agent session files
2. Parse — Raw session data (JSONL, JSON, markdown) is normalized into a StandardCodingContext
3. Extract — Key decisions, modified files, and errors are pulled via pattern matching and tool-use block analysis
4. Refine — Context is compressed to fit a token budget with target-agent-specific instructions
5. Deliver — Output goes to clipboard, file, or stdout

Development

# Watch mode
npm run dev

# Build
npm run build

# Run without global install
npx ts-node src/cli.ts list

Adding a New Adapter

Create src/adapters/myagent.ts implementing the AgentAdapter interface:

import type { AgentAdapter } from '../types.js';

export const myAgentAdapter: AgentAdapter = {
  name: 'myagent',
  displayName: 'My Agent',
  detect: async (projectPath) => { /* return true if history exists */ },
  getSessions: async (projectPath) => { /* return SessionInfo[] */ },
  capture: async (projectPath, sessionId?) => { /* return StandardCodingContext */ },
};

Then register it in src/adapters/index.ts.

License

MIT