@mmmjk/context-bridge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Added Claude Code <-> Codex session translation.
+- Added one-shot `copy` for independent target sessions.
+- Added `list`, `inspect`, `smoke`, `sync`, `watch`, `clean`, `dedupe`, `install-hook`, and MCP server commands.
+- Added loop prevention for generated sessions.
+- Added dirty-target conflict protection for sync.
+- Added prompt display cleanup for bootstrap and command-wrapper prompts.
+- Added npm packaging configuration for the `context-bridge` CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# Context Bridge
+
+**Language:** English | [简体中文](README.zh-CN.md)
+
+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:
+
+```bash
+npm install
+npm run build
+npm install -g .
+context-bridge --help
+```
+
+Install from npm after publishing:
+
+```bash
+npm install -g @mmmjk/context-bridge
+context-bridge --help
+ctxb --help
+```
+
+For local development without global installation:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+context-bridge copy <session-id>
+```
+
+## 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 <session-id>` |
+| `smoke` | Verify translation and print the resume command without live model execution. | `context-bridge smoke <session-id>` |
+| `translate` | Create a tracked generated session in the target harness. | `context-bridge translate <session-id>` |
+| `copy` | Create an independent target session without sync tracking. | `context-bridge copy <session-id>` |
+| `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 <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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```text
+~/.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
+
+```bash
+npm run build
+npm test
+npm run pack:dry
+```
+
+Release notes are in `CHANGELOG.md`. Publishing steps are in `docs/RELEASE.md`. Implementation details are in `docs/ARCHITECTURE.md`.

package/README.zh-CN.md

@@ -0,0 +1,275 @@
+# Context Bridge
+
+**语言：** [English](README.md) | 简体中文
+
+Context Bridge 是一个本地优先的编码代理会话互操作层。它通过统一的 canonical intermediate representation，在 Claude Code、Codex 和支持 MCP 的自动化工具之间迁移 JSONL 会话历史，并尽量保留跨 agent 恢复工作所需的操作上下文。
+
+它适合同时使用多个 CLI agent 的开发者：你可以迁移 session、一次性复制 session、批量同步最近 session，也可以让 MCP host 用结构化工具读取和准备恢复命令。
+
+## 为什么需要它
+
+现代编码代理的 session 不只是聊天记录，还包含 user turn、assistant output、tool call、文件操作、shell 命令、工作目录、时间戳和标题等执行轨迹。但这些轨迹通常被锁在各自 harness 的 JSONL 格式里。
+
+Context Bridge 提供一个轻量转换边界：
+
+- **Canonical IR**：把不同 agent 的事件规范化成统一 `Session` 模型。
+- **双向 adapter**：Claude Code 和 Codex 各自负责 ingest/render。
+- **来源感知同步**：生成 session 可识别、可清理、可去重，并避免再次作为同步源。
+- **独立复制模式**：可以复制到另一个 agent，但不建立后续同步关系。
+- **本地 MCP surface**：让 MCP host 能列出 session、触发转换并准备恢复命令。
+
+## 能力概览
+
+| 能力 | 说明 |
+| --- | --- |
+| Session translation | Claude Code JSONL 与 Codex JSONL 双向转换。 |
+| Session copy | 生成新的独立目标 session，不写追踪元数据。 |
+| Session index | 跨 agent 列出和查看本地 session，并展示可读提示词。 |
+| Batch sync | 扫描最近原生 session，生成确定性目标 session。 |
+| Divergence protection | 目标 session 分叉后默认跳过，除非使用 `--force`。 |
+| Loop prevention | 避免生成 session 再被同步成新的生成链。 |
+| Hook integration | 安装 Claude Code Stop hook 或 Codex notify hook，轻量自动同步。 |
+| MCP server | 通过 stdio 向 MCP host 暴露 session 工具。 |
+
+## 安装
+
+要求：
+
+- Node.js `>=20`
+
+从当前项目安装：
+
+```bash
+npm install
+npm run build
+npm install -g .
+context-bridge --help
+```
+
+发布后从 npm 安装：
+
+```bash
+npm install -g @mmmjk/context-bridge
+context-bridge --help
+ctxb --help
+```
+
+本地开发可直接运行：
+
+```bash
+node dist/src/cli.js --help
+```
+
+主命令名是 `context-bridge`，同时会安装更短的别名 `ctxb`。
+
+## 快速开始
+
+找到 session，验证转换，再正式迁移：
+
+```bash
+context-bridge list --harness both --days 30 -n 20
+context-bridge inspect <session-id>
+context-bridge smoke <session-id>
+context-bridge translate <session-id>
+```
+
+同样可以使用短别名：
+
+```bash
+ctxb list --harness both --days 30 -n 20
+ctxb translate <session-id>
+```
+
+执行 `translate` 输出的 resume 命令，并替换 `<your prompt>`。
+
+如果只想一次性复制到另一个 agent：
+
+```bash
+context-bridge copy <session-id>
+```
+
+## 心智模型
+
+核心有三条路径：
+
+| 路径 | 适用场景 | 结果 |
+| --- | --- | --- |
+| `translate` | 需要生成可识别的迁移产物。 | 带来源元数据的目标 session。 |
+| `copy` | 需要独立、原生观感的目标 session。 | 无同步追踪的新目标 session。 |
+| `sync` / `watch` | 需要自动镜像最近原生 session。 | 带 fingerprint 状态的确定性目标 session。 |
+
+`translate` 和 `sync` 是 provenance-aware 的：生成物后续可识别、可清理、可去重，并会被跳过以避免链式迁移。
+
+`copy` 是刻意不追踪的：它复用同一套 canonical 转换管线，但不写 `source_harness`、`originator: "context-bridge"`、`context-bridge-meta` 和 `[from ...]` 标题前缀。
+
+## 命令参考
+
+| 命令 | 作用 | 示例 |
+| --- | --- | --- |
+| `list` | 用紧凑表格列出本地 session。 | `context-bridge list --harness both --days 7 -n 20` |
+| `inspect` | 用 JSON 输出单个 session 摘要。 | `context-bridge inspect <session-id>` |
+| `smoke` | 验证转换并输出恢复命令，不执行真实模型。 | `context-bridge smoke <session-id>` |
+| `translate` | 在目标 harness 生成可追踪迁移 session。 | `context-bridge translate <session-id>` |
+| `copy` | 生成无同步追踪的独立目标 session。 | `context-bridge copy <session-id>` |
+| `sync` | 批量同步最近原生 session。 | `context-bridge sync --direction both --days 365` |
+| `watch` | 按间隔重复同步，或用 `--once` 只跑一次。 | `context-bridge watch --direction both --days 1 -i 30` |
+| `clean` | 删除生成的迁移 session。 | `context-bridge clean --dry-run` |
+| `dedupe` | 删除重复的生成 session。 | `context-bridge dedupe --dry-run` |
+| `install-hook` | 安装自动同步 hook。 | `context-bridge install-hook --target codex` |
+| `mcp serve` | 启动 stdio MCP server。 | `context-bridge mcp serve` |
+| `mcp config-snippet` | 输出 MCP host 配置片段。 | `context-bridge mcp config-snippet` |
+
+常用参数：
+
+- `--from <claude-code|codex>` 和 `--to <claude-code|codex>`：覆盖自动推断方向。
+- `--target-dir <dir>`：指定目标写入目录。
+- `--allow-generated`：允许 `translate` 或 `smoke` 读取生成 session。
+- `--source <all|native|claude|codex>`：按来源筛选 `list`。
+- `--force`：让 `sync` 重新生成被追踪目标。
+- `--include-active`：让 `sync` 包含当前活跃 Claude Code session。
+
+## 常见工作流
+
+### 迁移单个 Session
+
+```bash
+context-bridge list --harness both --days 14 -n 20
+context-bridge smoke <session-id>
+context-bridge translate <session-id>
+```
+
+这会生成一个目标 session，并输出恢复命令。适合希望迁移产物保持可识别、可清理、可同步的场景。
+
+### 无来源复制
+
+```bash
+context-bridge copy <session-id>
+```
+
+每次都会创建新的目标 session id。在 `list` 和 `inspect` 中，复制结果表现为原生 session：`Source` 为空，`source_harness` 为 `null`，清理命令不会把它当成生成物。
+
+### 同步最近 Session
+
+```bash
+context-bridge sync --direction both --days 365
+```
+
+支持方向：
+
+- `both`
+- `cc-to-codex`
+- `codex-to-cc`
+
+`sync` 会在 `~/.cache/context-bridge/` 记录源和目标 fingerprint。如果源和目标之后都发生变化，目标会被视为分叉并跳过。
+
+### 安装轻量 Hook
+
+```bash
+context-bridge install-hook --target claude-code
+context-bridge install-hook --target codex
+```
+
+Hook 是幂等的，并带有 `context_bridge.cli sync` 标记。
+
+## 会话列表
+
+`list` 用于快速扫描和选择：
+
+- `Modified`：本地时区 `yyyy-mm-dd hh:mm:ss`。
+- `Harness`：当前 session 所在 agent。
+- `Source`：原生/copy session 为空；生成 session 显示 `claude` 或 `codex`。
+- `CWD`：工作目录。
+- `Display Prompt`：过滤启动噪声后的可读标题或提示词。
+
+`inspect` 输出机器可读字段，包括 `first_prompt`、`display_prompt`、`session_title`、`source_harness`、`launch_context`、`start_command` 和 `resume_command`。
+
+## MCP Tools
+
+启动服务：
+
+```bash
+context-bridge mcp serve
+```
+
+可用工具：
+
+- `list_sessions`
+- `translate_session`
+- `sync_now`
+- `find_session`
+- `prepare_resume`
+- `resume_with_prompt`
+
+`resume_with_prompt` 只返回可执行命令，不启动真实模型进程。
+
+## 转移语义
+
+### 完全可转移
+
+| 数据 | 说明 |
+| --- | --- |
+| 用户和助手文本 | 普通文本回合会保留。 |
+| Shell 命令 | 常见 shell tool call 会跨 harness 映射。 |
+| 文件读写编辑删除移动 | Claude Code 文件工具和 Codex `apply_patch` 会映射为统一文件操作。 |
+| 搜索/glob 操作 | 常见 grep/glob 模式会保留。 |
+| Tool 结果 | 文本输出、call id 和错误标记在存在时会保留。 |
+| Session 标题、cwd、时间戳、id | 保留或重新生成为目标原生元数据。 |
+
+### 部分可转移
+
+| 数据 | 限制 |
+| --- | --- |
+| 目标 agent 没有等价能力的 tool call | 会保守渲染，不等价于原生 tool replay。 |
+| Web search 和 MCP call | 会保留为 canonical event；目标原生行为取决于可用工具。 |
+| 附件和 developer note | 可能渲染为 JSON 文本或 developer note。 |
+| Reasoning summary | 明文 summary 可转移；加密或签名 payload 不可转移。 |
+| Git、模型、权限、启动元数据 | 存在时会捕获；缺失字段无法重建。目标 session 不强制指定模型。 |
+| Subagent transcript 和 compaction 边界 | 作为可读历史或有损标记保留，不恢复运行态。 |
+
+### 不可转移
+
+| 数据 | 例子 |
+| --- | --- |
+| 加密或签名 reasoning payload | 隐藏 reasoning、签名、加密 compaction 内容。 |
+| 启动 agent 的完整原始 shell 命令 | alias、wrapper、环境变量前缀、完整 argv。 |
+| 转换过程中的实时模型执行 | `smoke` 和 MCP helper 只准备文件/命令。 |
+| Codex SQLite picker cache | 会写 JSONL 和 `session_index.jsonl`，不修改 SQLite cache。 |
+| 原生 plan/task UI 状态 | 有状态 checklist 和 UI-only 状态不会重建。 |
+| 外部服务状态 | 浏览器登录态、云端 job、远端 tool cache、凭证。 |
+| 未支持的 harness 格式 | 没有 adapter 的任何 session 格式。 |
+
+## 文件布局
+
+目标 session 目录：
+
+- Claude Code：`~/.claude/projects/.../*.jsonl`
+- Codex：`~/.codex/sessions/.../*.jsonl`
+
+Codex 标题索引：
+
+- `~/.codex/session_index.jsonl`
+
+Context Bridge 同步状态：
+
+```text
+~/.cache/context-bridge/
+```
+
+## 设计原则
+
+- **Local-first**：没有托管控制面，不上传远端 session。
+- **Adapter isolation**：harness 特定解析逻辑只存在于对应 adapter。
+- **Canonical-first translation**：所有转换都经过统一 `Session` 模型。
+- **Conservative lossiness**：不支持的结构显式降级表示，而不是静默丢弃。
+- **Destructive safety**：清理命令只处理可识别的生成 session。
+- **Model neutrality**：目标 session 不强制沿用源模型，恢复时使用目标 agent 当前默认配置。
+
+## 开发
+
+```bash
+npm run build
+npm test
+npm run pack:dry
+```
+
+发布记录见 `CHANGELOG.md`。发布步骤见 `docs/RELEASE.md`。实现细节见 `docs/ARCHITECTURE.md`。

package/dist/src/adapters/claude-code/index.js

@@ -0,0 +1,2 @@
+export { ingest } from "./ingest.js";
+export { render, encodeCwd, setCcProjects } from "./render.js";