convez.ai
MCP ServerAutomaçãoAvançado
conrad621

Context Bridge

conrad621/context-bridge

Migração local de sessões entre agentes de código sem lock-in

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que permite migração e sincronização de contexto de sessão entre agentes de código (Claude Code, Codex) através de uma representação intermediária canônica. Preserva histórico JSONL, operações de arquivo, comandos shell e metadados de execução para retomada contínua de trabalho entre diferentes harnesses.

Instalação

$npx convez-ai conrad621/context-bridge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Migrar sessão de Claude Code para Codex mantendo contexto completo
  • Duplicar sessão de trabalho para experimentação paralela
  • Sincronizar automaticamente sessões entre múltiplos agentes CLI
  • Descobrir e inspecionar histórico de sessões locais
  • Resumir trabalho em outro agente sem perder rastreamento de execução

Veredito

Ferramenta especializada para quem trabalha com múltiplos agentes de código e precisa mobilidade de contexto sem serviço hospedado. Implementação sólida em TypeScript com adapter bidirecional e proteção contra divergência, mas nicho restrito a desenvolvedores que usam simultaneamente Claude Code e Codex.

README

A tradução para o português deste README ainda está na fila.

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

CapabilityDescription
Session translationConvert Claude Code JSONL to Codex JSONL, and Codex JSONL to Claude Code JSONL.
Session copyCreate a fresh target-agent session with no tracking metadata.
Session indexList and inspect local sessions across harnesses with readable display prompts.
Batch syncScan recent original sessions and generate deterministic tracked targets.
Divergence protectionSkip tracked targets that were modified after generation unless --force is used.
Loop preventionPrevent generated sessions from being re-translated into new generated chains.
Hook integrationInstall Claude Code Stop hooks or Codex notify hooks for lightweight auto-sync.
MCP serverExpose 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 <session-id>
context-bridge smoke <session-id>
context-bridge translate <session-id>

The same commands can be run with the short alias:

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

Run the resume command printed by translate, then replace <your prompt>.

Create a one-shot independent duplicate instead:

context-bridge copy <session-id>

Mental Model

There are three primary flows:

FlowUse whenResult
translateYou want a generated migration artifact.A target session with source metadata.
copyYou want an independent native-looking target session.A fresh target session with no sync tracking.
sync / watchYou 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

CommandPurposeExample
listList local sessions in a compact table.context-bridge list --harness both --days 7 -n 20
inspectPrint one indexed session summary as JSON.context-bridge inspect <session-id>
smokeVerify translation and print the resume command without live model execution.context-bridge smoke <session-id>
translateCreate a tracked generated session in the target harness.context-bridge translate <session-id>
copyCreate an independent target session without sync tracking.context-bridge copy <session-id>
syncBatch-sync recent original sessions.context-bridge sync --direction both --days 365
watchRe-run sync on an interval, or once with --once.context-bridge watch --direction both --days 1 -i 30
cleanRemove generated translated sessions.context-bridge clean --dry-run
dedupeRemove duplicate generated sessions.context-bridge dedupe --dry-run
install-hookInstall automatic sync hooks.context-bridge install-hook --target codex
mcp serveStart the stdio MCP server.context-bridge mcp serve
mcp config-snippetPrint an MCP host config snippet.context-bridge mcp config-snippet

Common options:

  • --from <claude-code|codex> and --to <claude-code|codex> override inferred direction.
  • --target-dir <dir> writes generated files to a custom target root.
  • --allow-generated lets translate or smoke read a generated session.
  • --source <all|native|claude|codex> 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 <session-id>
context-bridge translate <session-id>

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 <session-id>

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

DataNotes
User and assistant textPlain text turns are preserved.
Shell commandsCommon shell tool calls are mapped across harnesses.
File read/write/edit/delete/moveClaude Code file tools and Codex apply_patch are mapped to canonical file operations.
Search/glob operationsCommon grep/glob patterns are preserved.
Tool resultsText output, call ids, and error flags are preserved when present.
Session title, cwd, timestamps, idsPreserved or regenerated as target-native metadata.

Partially Transferable

DataLimitation
Tool calls without a target equivalentRendered conservatively instead of replayed as a native tool.
Web search and MCP callsPreserved as canonical events; native behavior depends on target tool availability.
Attachments and developer notesMay render as JSON text or developer notes.
Reasoning summariesPlain summaries can transfer; encrypted or signed payloads cannot.
Git, model, permissions, launch metadataCaptured when present; missing source fields cannot be reconstructed. Target sessions do not force a model override.
Subagent transcripts and compaction boundariesPreserved as readable history or lossy markers, not as live runtime state.

Not Transferable

DataExamples
Encrypted or signed reasoning payloadsHidden reasoning bodies, signatures, encrypted compaction content.
Exact original shell command used to launch the agentAliases, wrappers, env prefixes, complete argv.
Live model execution during transfersmoke and MCP helpers prepare files/commands only.
Codex SQLite picker cacheJSONL and session_index.jsonl are written; SQLite cache is not mutated.
Native plan/task UI stateStateful checklists and UI-only state are not reconstructed.
External service stateBrowser sessions, cloud jobs, remote tool caches, credentials.
Unsupported harness formatsAny 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.

Ver o original no GitHub

Bom para

Relacionados