Local-first session bridge

Bridge coding-agent sessions without losing context.

Translate, copy, and sync Claude Code and Codex session history without losing the operational trail.

Start using it View npm

context-bridge translate

Claude Code JSONL ingest

Canonical Session normalize

Codex JSONL render

$ ctxb translate <session-id>
created target session
resume: codex resume ...

Local first No hosted service required

Bidirectional Claude Code and Codex

MCP ready Structured session tools

Why it matters

A session is not a chat log. It is the worksite.

Coding-agent sessions include intent, assistant output, tool calls, shell commands, file operations, working directories, timestamps, and titles. Context Bridge normalizes that trace into a shared model, then renders it into a format the next tool can resume.

Pain points

The hard part of multi-agent work is not launching another CLI.

The cost shows up after the switch: context fragments, traces break, and you start explaining the same work again. Context Bridge targets that hidden handoff cost.

Lost context

Context is locked inside private formats

Claude Code and Codex both write JSONL, but their event structures differ. Switching tools usually means copying a summary by hand.

Broken trace

Tool calls and file operations are hard to carry over

A real coding session includes shell commands, patches, file reads, working directories, and errors. Plain chat export is not enough.

Manual handoff

Manual handoff gets less reliable over time

Long tasks, multi-day work, and reviews can miss critical commands or decisions when the handoff is written from memory.

Sync loops

Automatic sync can create duplicate chains

Without provenance, generated sessions can be translated again and again, polluting local history.

Translate

Create a marked migration session that can later be cleaned, deduped, and skipped as a future sync source.

Copy

Create a one-shot native-looking target session without sync tracking metadata.

Sync / Watch

Mirror recent native sessions in a deterministic way for long-running two-agent workflows.

Capabilities

Infrastructure for cross-agent coding workflows.

Canonical IR

Normalize harness-specific events into one shared Session model.

Adapter Boundary

Claude Code and Codex each own clear ingest and render logic.

Provenance-aware Sync

Generated sessions are identifiable, skippable, cleanable, and safe from looped translation.

Session Index

List, inspect, and filter local sessions across harnesses.

Hook Integration

Install Claude Code Stop hooks or Codex notify hooks for lightweight auto-sync.

MCP Server

Expose session lookup, translation, and resume-command preparation over stdio.

Case tours

Concrete places where the bridge fits.

Case 01

Continue a half-finished task in another agent

Move a session after the discovery, implementation, and test history already exist, then let the next agent continue from that trace.

ctxb list --harness claude-code
ctxb smoke <session-id>
ctxb translate <session-id> --to codex

Case 02

Reuse a strong investigation without sync metadata

Copy architecture notes, risk findings, file context, and command output into a fresh target session without marking it as generated.

ctxb copy <session-id>

# no provenance markers
# fresh target session id

Case 03

Switch between two CLI agents every day

Use sync or watch to mirror recent native sessions while fingerprints and source markers prevent duplicate chains.

ctxb sync --direction both --days 14
ctxb watch --direction both --days 1 -i 30

Case 04

Expose session operations to MCP automation

Let MCP hosts list sessions, trigger conversion, and receive executable resume commands without hard-coding local agent paths.

ctxb mcp config-snippet
ctxb mcp serve

Case 05

Keep a traceable review chain before release

Let one agent implement and another review while the generated target session keeps source metadata for later audit.

ctxb inspect <source-session>
ctxb translate <source-session>
ctxb inspect <target-session>

Case 06

Clean migration artifacts from local history

Use dry-run cleanup and dedupe commands to inspect generated sessions before removing confirmed migration artifacts.

ctxb clean --dry-run
ctxb dedupe --dry-run

# rerun without --dry-run when ready

Usage guide

Start with the conservative path.

List sessions first, then run a smoke check. Once the direction and resume command look right, choose translate, copy, or sync.

01
Install the CLI

Global installation gives you both context-bridge and the short ctxb alias.
```
npm install -g @mmmjk/context-bridge
ctxb --help
```
02
Find the session to move

Start with a short time window, then widen --days if needed.
```
ctxb list --harness both --days 7 -n 20
ctxb inspect <session-id>
```
03
Run a smoke check first

Smoke verifies conversion and prints the resume command without running a live model.
```
ctxb smoke <session-id>
ctxb smoke <session-id> --to codex
```
04
Choose migration, copy, or sync

Use translate for traceable migration, copy for a clean independent start, and sync or watch for long-term mirroring.
```
ctxb translate <session-id>
ctxb copy <session-id>
ctxb sync --direction both --days 14
```
05
Run the printed resume command

Translate prints the target agent resume command. Replace the prompt with your next task and continue.
```
# printed by translate
codex resume ... "<your next prompt>"
```

CLI first

A few commands move context to the next tool.

The primary command is context-bridge, with ctxb as a shorter alias. Core operations are local file reads and writes.

ctxb list --harness both --days 30 -n 20
ctxb inspect <session-id>
ctxb smoke <session-id>
ctxb translate <session-id>

ctxb copy <session-id>

# fresh target session
# no sync tracking metadata

ctxb sync --direction both --days 365
ctxb watch --direction both --days 1 -i 30

Install

Install from npm.

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