Context Bridge

Context Bridge

Language: English | 简体中文

Website: https://conrad621.github.io/context-bridge Repository: https://github.com/conrad621/context-bridge

Context Bridge is a local-first session interoperability layer for coding agents. It moves JSONL session history between Claude Code, Codex, and MCP-aware automation surfaces through a canonical intermediate representation, preserving enough operational context to resume work across harness boundaries.

It is designed for developers who use more than one CLI agent and need controlled session migration, one-shot duplication, local sync, and machine-readable session discovery without relying on a hosted service.

Why It Exists

Modern coding agents store rich execution traces: user turns, assistant output, tool calls, file operations, shell commands, working directories, timestamps, and display titles. Those traces are valuable, but they are usually locked inside harness-specific JSONL formats.

Context Bridge provides a small translation boundary:

• Canonical IR: harness-specific events are normalized into a shared Session model.
• Bidirectional adapters: Claude Code and Codex each own their ingest/render logic.
• Provenance-aware sync: generated sessions are marked, tracked, deduped, and skipped as future sources.
• Independent copy mode: sessions can be duplicated into another agent without creating a sync relationship.
• Local MCP surface: external MCP hosts can list, translate, and prepare resume commands.

Capabilities

| Capability | Description | | --- | --- | | Session translation | Convert Claude Code JSONL to Codex JSONL, and Codex JSONL to Claude Code JSONL. | | Session copy | Create a fresh target-agent session with no tracking metadata. | | Session index | List and inspect local sessions across harnesses with readable display prompts. | | Batch sync | Scan recent original sessions and generate deterministic tracked targets. | | Divergence protection | Skip tracked targets that were modified after generation unless --force is used. | | Loop prevention | Prevent generated sessions from being re-translated into new generated chains. | | Hook integration | Install Claude Code Stop hooks or Codex notify hooks for lightweight auto-sync. | | MCP server | Expose session operations to MCP-aware hosts through stdio. |

Installation

Requirements:

• Node.js >=20

Install from this checkout:

npm install
npm run build
npm install -g .
context-bridge --help

Install from npm after publishing:

npm install -g @mmmjk/context-bridge
context-bridge --help
ctxb --help

For local development without global installation:

node dist/src/cli.js --help

The primary binary name is context-bridge. A shorter alias, ctxb, is also installed.

Quick Start

Find a session, verify conversion, then translate it:

context-bridge list --harness both --days 30 -n 20
context-bridge inspect 
context-bridge smoke 
context-bridge translate 

The same commands can be run with the short alias:

ctxb list --harness both --days 30 -n 20
ctxb translate 

Run the resume command printed by translate, then replace ``.

Create a one-shot independent duplicate instead:

context-bridge copy 

Mental Model

There are three primary flows:

| Flow | Use when | Result | | --- | --- | --- | | translate | You want a generated migration artifact. | A target session with source metadata. | | copy | You want an independent native-looking target session. | A fresh target session with no sync tracking. | | sync / watch | You want recent original sessions mirrored automatically. | Deterministic tracked targets with fingerprint state. |

translate and sync are provenance-aware. Their outputs can be identified later, cleaned, deduped, and protected from chain translation.

copy is deliberately untracked. It uses the same canonical conversion pipeline, but omits source_harness, originator: "context-bridge", context-bridge-meta, and [from ...] title prefixes.

Command Reference

| Command | Purpose | Example | | --- | --- | --- | | list | List local sessions in a compact table. | context-bridge list --harness both --days 7 -n 20 | | inspect | Print one indexed session summary as JSON. | context-bridge inspect | | smoke | Verify translation and print the resume command without live model execution. | context-bridge smoke | | translate | Create a tracked generated session in the target harness. | context-bridge translate | | copy | Create an independent target session without sync tracking. | context-bridge copy | | sync | Batch-sync recent original sessions. | context-bridge sync --direction both --days 365 | | watch | Re-run sync on an interval, or once with --once. | context-bridge watch --direction both --days 1 -i 30 | | clean | Remove generated translated sessions. | context-bridge clean --dry-run | | dedupe | Remove duplicate generated sessions. | context-bridge dedupe --dry-run | | install-hook | Install automatic sync hooks. | context-bridge install-hook --target codex | | mcp serve | Start the stdio MCP server. | context-bridge mcp serve | | mcp config-snippet | Print an MCP host config snippet. | context-bridge mcp config-snippet |

Common options:

• --from and --to override inferred direction.
• --target-dir writes generated files to a custom target root.
• --allow-generated lets translate or smoke read a generated session.
• --source filters list by origin.
• --force lets sync regenerate tracked targets.
• --include-active lets sync include the active Claude Code session.

Workflows

Move One Session

context-bridge list --harness both --days 14 -n 20
context-bridge smoke 
context-bridge translate 

This creates a generated target session and prints the resume command. Use this when you want the migration to remain identifiable as a Context Bridge artifact.

Copy Without Provenance

context-bridge copy 

This creates a new target session id every time. In list and inspect, the copied session appears native: Source is blank, source_harness is null, and cleanup commands will not treat it as generated.

Sync Recent Sessions

context-bridge sync --direction both --days 365

Directions:

• both
• cc-to-codex
• codex-to-cc

sync records source and target fingerprints under ~/.cache/context-bridge/. If both source and target change after generation, the target is considered divergent and is skipped as a conflict.

Install Lightweight Hooks

context-bridge install-hook --target claude-code
context-bridge install-hook --target codex

Hooks are idempotent and marked with context_bridge.cli sync.

Session Listing

list is optimized for scanning and selection:

• Modified: local timestamp in yyyy-mm-dd hh:mm:ss.
• Harness: current session store.
• Source: blank for native/copy sessions, claude or codex for generated sessions.
• CWD: working directory.
• Display Prompt: readable title or prompt with bootstrap noise filtered out.

inspect exposes raw machine-readable fields such as first_prompt, display_prompt, session_title, source_harness, launch_context, start_command, and resume_command.

MCP Tools

Start the server:

context-bridge mcp serve

Available tools:

• list_sessions
• translate_session
• sync_now
• find_session
• prepare_resume
• resume_with_prompt

resume_with_prompt returns a command to run. It does not execute a live model process.

Transfer Semantics

Fully Transferable

| Data | Notes | | --- | --- | | User and assistant text | Plain text turns are preserved. | | Shell commands | Common shell tool calls are mapped across harnesses. | | File read/write/edit/delete/move | Claude Code file tools and Codex apply_patch are mapped to canonical file operations. | | Search/glob operations | Common grep/glob patterns are preserved. | | Tool results | Text output, call ids, and error flags are preserved when present. | | Session title, cwd, timestamps, ids | Preserved or regenerated as target-native metadata. |

Partially Transferable

| Data | Limitation | | --- | --- | | Tool calls without a target equivalent | Rendered conservatively instead of replayed as a native tool. | | Web search and MCP calls | Preserved as canonical events; native behavior depends on target tool availability. | | Attachments and developer notes | May render as JSON text or developer notes. | | Reasoning summaries | Plain summaries can transfer; encrypted or signed payloads cannot. | | Git, model, permissions, launch metadata | Captured when present; missing source fields cannot be reconstructed. Target sessions do not force a model override. | | Subagent transcripts and compaction boundaries | Preserved as readable history or lossy markers, not as live runtime state. |

Not Transferable

| Data | Examples | | --- | --- | | Encrypted or signed reasoning payloads | Hidden reasoning bodies, signatures, encrypted compaction content. | | Exact original shell command used to launch the agent | Aliases, wrappers, env prefixes, complete argv. | | Live model execution during transfer | smoke and MCP helpers prepare files/commands only. | | Codex SQLite picker cache | JSONL and session_index.jsonl are written; SQLite cache is not mutated. | | Native plan/task UI state | Stateful checklists and UI-only state are not reconstructed. | | External service state | Browser sessions, cloud jobs, remote tool caches, credentials. | | Unsupported harness formats | Any harness without an adapter. |

Filesystem Layout

Target session stores:

• Claude Code: ~/.claude/projects/.../*.jsonl
• Codex: ~/.codex/sessions/.../*.jsonl

Codex title index:

• ~/.codex/session_index.jsonl

Context Bridge sync state:

~/.cache/context-bridge/

Design Principles

• Local-first: no hosted control plane, no remote session upload.
• Adapter isolation: harness-specific parsing stays inside harness adapters.
• Canonical-first translation: all conversions pass through the shared Session model.
• Conservative lossiness: unsupported structures are represented explicitly instead of silently discarded.
• Destructive safety: cleanup only targets sessions that can be identified as generated.
• Model neutrality: target sessions do not force a source model; resumed agents use their current defaults.

Development

npm run build
npm test
npm run pack:dry

Release notes are in CHANGELOG.md. Publishing steps are in RELEASE.md.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: conrad621
• Source: conrad621/context-bridge
• License: MIT
• Homepage: https://conrad621.github.io/context-bridge/

Install and usage instructions live in the source repository linked above.