{"id":51049503,"url":"https://github.com/conrad621/context-bridge","last_synced_at":"2026-06-22T16:01:48.487Z","repository":{"id":364932501,"uuid":"1269747148","full_name":"conrad621/context-bridge","owner":"conrad621","description":"跨编码 Agent 无缝迁移会话上下文，让Claude Code、Codex之间的会话上下文自由迁移、复制和同步。","archived":false,"fork":false,"pushed_at":"2026-06-15T05:29:04.000Z","size":62,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-15T07:22:16.942Z","etag":null,"topics":["agent-sessions","ai-agents","claude-code","cli","codex","developer-tools","mcp","session-management"],"latest_commit_sha":null,"homepage":"https://conrad621.github.io/context-bridge/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/conrad621.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T04:04:13.000Z","updated_at":"2026-06-15T05:41:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/conrad621/context-bridge","commit_stats":null,"previous_names":["conrad621/context-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/conrad621/context-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conrad621%2Fcontext-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conrad621%2Fcontext-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conrad621%2Fcontext-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conrad621%2Fcontext-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/conrad621","download_url":"https://codeload.github.com/conrad621/context-bridge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conrad621%2Fcontext-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34655719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-sessions","ai-agents","claude-code","cli","codex","developer-tools","mcp","session-management"],"created_at":"2026-06-22T16:01:47.448Z","updated_at":"2026-06-22T16:01:48.474Z","avatar_url":"https://github.com/conrad621.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Context Bridge\n\n**Language:** English | [简体中文](https://github.com/conrad621/context-bridge/blob/master/README.zh-CN.md)\n\n**Website:** https://conrad621.github.io/context-bridge\n**Repository:** https://github.com/conrad621/context-bridge\n\nContext 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.\n\nIt 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.\n\n## Why It Exists\n\nModern 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.\n\nContext Bridge provides a small translation boundary:\n\n- **Canonical IR**: harness-specific events are normalized into a shared `Session` model.\n- **Bidirectional adapters**: Claude Code and Codex each own their ingest/render logic.\n- **Provenance-aware sync**: generated sessions are marked, tracked, deduped, and skipped as future sources.\n- **Independent copy mode**: sessions can be duplicated into another agent without creating a sync relationship.\n- **Local MCP surface**: external MCP hosts can list, translate, and prepare resume commands.\n\n## Capabilities\n\n| Capability | Description |\n| --- | --- |\n| Session translation | Convert Claude Code JSONL to Codex JSONL, and Codex JSONL to Claude Code JSONL. |\n| Session copy | Create a fresh target-agent session with no tracking metadata. |\n| Session index | List and inspect local sessions across harnesses with readable display prompts. |\n| Batch sync | Scan recent original sessions and generate deterministic tracked targets. |\n| Divergence protection | Skip tracked targets that were modified after generation unless `--force` is used. |\n| Loop prevention | Prevent generated sessions from being re-translated into new generated chains. |\n| Hook integration | Install Claude Code Stop hooks or Codex notify hooks for lightweight auto-sync. |\n| MCP server | Expose session operations to MCP-aware hosts through stdio. |\n\n## Installation\n\nRequirements:\n\n- Node.js `\u003e=20`\n\nInstall from this checkout:\n\n```bash\nnpm install\nnpm run build\nnpm install -g .\ncontext-bridge --help\n```\n\nInstall from npm after publishing:\n\n```bash\nnpm install -g @mmmjk/context-bridge\ncontext-bridge --help\nctxb --help\n```\n\nFor local development without global installation:\n\n```bash\nnode dist/src/cli.js --help\n```\n\nThe primary binary name is `context-bridge`. A shorter alias, `ctxb`, is also installed.\n\n## Quick Start\n\nFind a session, verify conversion, then translate it:\n\n```bash\ncontext-bridge list --harness both --days 30 -n 20\ncontext-bridge inspect \u003csession-id\u003e\ncontext-bridge smoke \u003csession-id\u003e\ncontext-bridge translate \u003csession-id\u003e\n```\n\nThe same commands can be run with the short alias:\n\n```bash\nctxb list --harness both --days 30 -n 20\nctxb translate \u003csession-id\u003e\n```\n\nRun the resume command printed by `translate`, then replace `\u003cyour prompt\u003e`.\n\nCreate a one-shot independent duplicate instead:\n\n```bash\ncontext-bridge copy \u003csession-id\u003e\n```\n\n## Mental Model\n\nThere are three primary flows:\n\n| Flow | Use when | Result |\n| --- | --- | --- |\n| `translate` | You want a generated migration artifact. | A target session with source metadata. |\n| `copy` | You want an independent native-looking target session. | A fresh target session with no sync tracking. |\n| `sync` / `watch` | You want recent original sessions mirrored automatically. | Deterministic tracked targets with fingerprint state. |\n\n`translate` and `sync` are provenance-aware. Their outputs can be identified later, cleaned, deduped, and protected from chain translation.\n\n`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.\n\n## Command Reference\n\n| Command | Purpose | Example |\n| --- | --- | --- |\n| `list` | List local sessions in a compact table. | `context-bridge list --harness both --days 7 -n 20` |\n| `inspect` | Print one indexed session summary as JSON. | `context-bridge inspect \u003csession-id\u003e` |\n| `smoke` | Verify translation and print the resume command without live model execution. | `context-bridge smoke \u003csession-id\u003e` |\n| `translate` | Create a tracked generated session in the target harness. | `context-bridge translate \u003csession-id\u003e` |\n| `copy` | Create an independent target session without sync tracking. | `context-bridge copy \u003csession-id\u003e` |\n| `sync` | Batch-sync recent original sessions. | `context-bridge sync --direction both --days 365` |\n| `watch` | Re-run sync on an interval, or once with `--once`. | `context-bridge watch --direction both --days 1 -i 30` |\n| `clean` | Remove generated translated sessions. | `context-bridge clean --dry-run` |\n| `dedupe` | Remove duplicate generated sessions. | `context-bridge dedupe --dry-run` |\n| `install-hook` | Install automatic sync hooks. | `context-bridge install-hook --target codex` |\n| `mcp serve` | Start the stdio MCP server. | `context-bridge mcp serve` |\n| `mcp config-snippet` | Print an MCP host config snippet. | `context-bridge mcp config-snippet` |\n\nCommon options:\n\n- `--from \u003cclaude-code|codex\u003e` and `--to \u003cclaude-code|codex\u003e` override inferred direction.\n- `--target-dir \u003cdir\u003e` writes generated files to a custom target root.\n- `--allow-generated` lets `translate` or `smoke` read a generated session.\n- `--source \u003call|native|claude|codex\u003e` filters `list` by origin.\n- `--force` lets `sync` regenerate tracked targets.\n- `--include-active` lets `sync` include the active Claude Code session.\n\n## Workflows\n\n### Move One Session\n\n```bash\ncontext-bridge list --harness both --days 14 -n 20\ncontext-bridge smoke \u003csession-id\u003e\ncontext-bridge translate \u003csession-id\u003e\n```\n\nThis 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.\n\n### Copy Without Provenance\n\n```bash\ncontext-bridge copy \u003csession-id\u003e\n```\n\nThis 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.\n\n### Sync Recent Sessions\n\n```bash\ncontext-bridge sync --direction both --days 365\n```\n\nDirections:\n\n- `both`\n- `cc-to-codex`\n- `codex-to-cc`\n\n`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.\n\n### Install Lightweight Hooks\n\n```bash\ncontext-bridge install-hook --target claude-code\ncontext-bridge install-hook --target codex\n```\n\nHooks are idempotent and marked with `context_bridge.cli sync`.\n\n## Session Listing\n\n`list` is optimized for scanning and selection:\n\n- `Modified`: local timestamp in `yyyy-mm-dd hh:mm:ss`.\n- `Harness`: current session store.\n- `Source`: blank for native/copy sessions, `claude` or `codex` for generated sessions.\n- `CWD`: working directory.\n- `Display Prompt`: readable title or prompt with bootstrap noise filtered out.\n\n`inspect` exposes raw machine-readable fields such as `first_prompt`, `display_prompt`, `session_title`, `source_harness`, `launch_context`, `start_command`, and `resume_command`.\n\n## MCP Tools\n\nStart the server:\n\n```bash\ncontext-bridge mcp serve\n```\n\nAvailable tools:\n\n- `list_sessions`\n- `translate_session`\n- `sync_now`\n- `find_session`\n- `prepare_resume`\n- `resume_with_prompt`\n\n`resume_with_prompt` returns a command to run. It does not execute a live model process.\n\n## Transfer Semantics\n\n### Fully Transferable\n\n| Data | Notes |\n| --- | --- |\n| User and assistant text | Plain text turns are preserved. |\n| Shell commands | Common shell tool calls are mapped across harnesses. |\n| File read/write/edit/delete/move | Claude Code file tools and Codex `apply_patch` are mapped to canonical file operations. |\n| Search/glob operations | Common grep/glob patterns are preserved. |\n| Tool results | Text output, call ids, and error flags are preserved when present. |\n| Session title, cwd, timestamps, ids | Preserved or regenerated as target-native metadata. |\n\n### Partially Transferable\n\n| Data | Limitation |\n| --- | --- |\n| Tool calls without a target equivalent | Rendered conservatively instead of replayed as a native tool. |\n| Web search and MCP calls | Preserved as canonical events; native behavior depends on target tool availability. |\n| Attachments and developer notes | May render as JSON text or developer notes. |\n| Reasoning summaries | Plain summaries can transfer; encrypted or signed payloads cannot. |\n| Git, model, permissions, launch metadata | Captured when present; missing source fields cannot be reconstructed. Target sessions do not force a model override. |\n| Subagent transcripts and compaction boundaries | Preserved as readable history or lossy markers, not as live runtime state. |\n\n### Not Transferable\n\n| Data | Examples |\n| --- | --- |\n| Encrypted or signed reasoning payloads | Hidden reasoning bodies, signatures, encrypted compaction content. |\n| Exact original shell command used to launch the agent | Aliases, wrappers, env prefixes, complete argv. |\n| Live model execution during transfer | `smoke` and MCP helpers prepare files/commands only. |\n| Codex SQLite picker cache | JSONL and `session_index.jsonl` are written; SQLite cache is not mutated. |\n| Native plan/task UI state | Stateful checklists and UI-only state are not reconstructed. |\n| External service state | Browser sessions, cloud jobs, remote tool caches, credentials. |\n| Unsupported harness formats | Any harness without an adapter. |\n\n## Filesystem Layout\n\nTarget session stores:\n\n- Claude Code: `~/.claude/projects/.../*.jsonl`\n- Codex: `~/.codex/sessions/.../*.jsonl`\n\nCodex title index:\n\n- `~/.codex/session_index.jsonl`\n\nContext Bridge sync state:\n\n```text\n~/.cache/context-bridge/\n```\n\n## Design Principles\n\n- **Local-first**: no hosted control plane, no remote session upload.\n- **Adapter isolation**: harness-specific parsing stays inside harness adapters.\n- **Canonical-first translation**: all conversions pass through the shared `Session` model.\n- **Conservative lossiness**: unsupported structures are represented explicitly instead of silently discarded.\n- **Destructive safety**: cleanup only targets sessions that can be identified as generated.\n- **Model neutrality**: target sessions do not force a source model; resumed agents use their current defaults.\n\n## Development\n\n```bash\nnpm run build\nnpm test\nnpm run pack:dry\n```\n\nRelease notes are in `CHANGELOG.md`. Publishing steps are in `RELEASE.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconrad621%2Fcontext-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconrad621%2Fcontext-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconrad621%2Fcontext-bridge/lists"}