hist-bridge

用多个 AI 编程 Agent 协作时,在它们之间无缝衔接同一个对话。

当你用 Claude Code、Codex、Cursor 等多个 Agent 编码时——它们各有所长,但上下文断在每个工具里、互不相通。hist-bridge 把它们打通:在当前 Agent 里列出 / 搜索 / 摘要 / 载入其它 Agent 的历史会话,把它当作上下文接着往下做;再用「会话链 (thread)」把跨工具的多次往返当成一个连续对话来统一管理。

一句话:同一个编码任务,让不同 Agent 协同接力,而不是各聊各的。 想用 Codex 起草、用 Claude 深挖、用 Cursor 调,中间不丢上下文——这就是 hist-bridge 解决的事。

实现上是上下文接力(把历史对话作为上下文喂给当前 Agent 继续),不是无损的完整状态重放——跨厂商的内部推理状态/工具执行状态无法迁移。对"接着聊、接着做"而言完全够用。

支持来源:Claude Code、Codex、Cursor(含在 Cursor 里用 GLM 跑的会话)、以及另一个 z.ai 后端的 Claude Code(GLM)。

它能读哪些历史

Related MCP server: ccfolio

暴露的 MCP 工具

• list_sources() — 列出已配置来源及是否可用。

• list_conversations({source?, project?, query?, limit?}) — 列历史会话,按时间倒序。

• get_conversation({source, id, format?, max_messages?, include_reasoning?, include_tools?}) — 把某次会话渲染成可续接内容。format:markdown(完整 transcript,默认)| summary(紧凑交接卡)| json(结构化)。

• summarize_conversation({source, id}) — 抽取式压缩成「🎯目标 / ✅已完成 / ⚠️卡点 / 📋待办 / 🧭最后状态」交接卡。无需 LLM、确定性、省上下文,长会话优先用它。

• search_conversations({query, source?, limit?}) — 跨来源全文检索(先标题,后正文)。

会话链 (thread) —— 把跨工具的多次会话当成一个连续对话:

• link_thread({title?, members:[{source,id}...]}) — 把若干会话按 hop 顺序标记为同一条逻辑对话。

• list_threads() — 列出所有链及成员(含每个成员是否可用)。

• get_thread({thread_id, format?, max_messages?}) — 把整条链的成员会话按序合并成一个连续转写;自动剥掉 hist-bridge 自己嵌入过的转写块(# 历史会话: / # 🗂 交接摘要:)避免历史重复。

• summarize_thread({thread_id}) — 对整条链出一张交接卡。

• append_to_thread({thread_id, source, id}) — 在另一个工具续接产生新会话后,把它接到链尾。

• unlink_thread({thread_id}) — 删除链(只删关联,不动底层会话)。

线程元数据存在用户级目录(win:%APPDATA%\hist-bridge\threads.json;mac/linux:~/.config/hist-bridge/threads.json),可用 HIST_BRIDGE_THREAD_STORE 覆盖。典型用法:在 Claude 聊→载入 Codex 续→link_thread claude:<id> codex:<新id>→以后任一工具 get_thread/summarize_thread 就能把整条往返当一个对话载入,不再套娃。

摘要器(省上下文)

长会话(几十上百条消息)直接全量载入会吃掉大量上下文。summarize_conversation / format:"summary" 用确定性规则从归一化对话里抽取:首条用户消息→目标;write/edit 工具参数→改动文件;shell 命令→已运行命令;isError 结果→卡点;工具自带的 todo 列表(Cursor todos、Claude TodoWrite)→待办;最后一条真实用户/助手消息→当前状态。一张卡通常只有原文的几十分之一,但保留了「目标 + 进度 + 下一步」——续接问答足够。

安装

npm install
npm run build      # 生成 dist/

在 Claude Code 用

方式 A — 直接注册 MCP server(最快):

claude mcp add --scope user hist-bridge -- node "<绝对路径>/hist-bridge/dist/server.js"

之后在 Claude Code 里直接说:「列出我最近的 codex 对话」「把第 3 个载进来接着聊」。重启 Claude Code 生效。

方式 B — 作为插件安装(额外带 /resume 命令和续接技能): 本仓库已是合法插件结构(.claude-plugin/plugin.json 内联了 MCP server 声明,外加 commands/ + skills/)。通过你的插件 marketplace 或本地插件机制安装后,会多出:

• /hist-bridge:resume [codex|glm|claude|搜索词] 斜杠命令

• continue-foreign 技能(自动梳理目标/已完成/未完成再续接)

在 Codex 用

编辑 ~/.codex/config.toml,加:

[mcp_servers.hist-bridge]
command = "node"
args = ["<绝对路径>/hist-bridge/dist/server.js"]
startup_timeout_sec = 20

然后在 Codex 里就能调 list_conversations / get_conversation 等工具。Codex 自己的历史它本来就能 codex resume;这个 server 额外给它跨工具 + 统一检索。

配置 GLM 来源

GLM 有两个去处,按你怎么用分别覆盖:

1. 在 Cursor 里用 GLM → 已被 cursor 来源自动覆盖,按 model 字段(GLM-5 / GLM-5.1 等)就能认出来,无需额外配置。

2. 在另一个 z.ai 后端的 Claude Code 里用 GLM(文件格式同 Claude Code)→ 启用 glm 来源:

   • 环境变量(最简单):HIST_BRIDGE_GLM_ROOT=<那个实例的 projects 目录>(自动启用)。

   • 或改 config.json 里 sources.glm.root 并把 enabled 设为 true。

   • 若那份历史在另一台机器,把对应的 .jsonl 同步过来再指向即可。

Cursor 来源说明

• 默认按平台自动探测 state.vscdb 路径(win/mac/linux);也可在 config.json 的 sources.cursor.root 指定。

• 读取时会先把 state.vscdb 拷到临时目录再以只读打开,不碰你正在运行的 Cursor,也不会写回。

• 同一个库里也存着 cursorAuth/* 令牌——本工具只读 composerData/bubbleId,不会导出这些密钥。

调试 CLI(不连 MCP 直接试)

npm run cli -- sources
npm run cli -- list [codex|cursor|glm|claude] [--project X] [--query Y] [--limit N]
npm run cli -- get <source> <id> [--max N] [--json] [--reasoning]
npm run cli -- summarize <source> <id>      # 紧凑交接卡
npm run cli -- search <关键词> [source]

已知边界

• 会话格式是各工具私有且会变的;解析器做了防御,但厂商改格式时可能需要更新适配器。

• Codex 的推理(reasoning)是加密的,无法还原;Claude 不在 transcript 里存 system prompt(Codex 存),归一化时会体现这种不对称。

• search_conversations 的正文扫描有数量上限(默认 60 个会话)以控制开销;标题命中不受限。

• Cursor 读取依赖 Node 内置 node:sqlite(需 Node ≥ 22.13,本机 Node 24 直接可用;旧版本上 cursor 来源会被报为不可用而非报错)。读取时把 state.vscdb 连同 -wal/-shm 一起拷到私有临时目录(0600 权限、进程退出即删),以只读方式打开;副本含 cursorAuth/* 令牌,故不落在共享 /tmp、用完即清。

• 摘要器是确定性抽取式,不调 LLM:目标取首条用户消息、已完成取工具调用、卡点取报错结果、待办取工具原生 todo 列表——它不"理解"语义,只做高信噪比的结构化提取。