npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@gxcsoccer/agenthub

v0.4.3

Published

One API across coding harnesses: existing sessions, messages and explicit delivery semantics.

Readme

AgentHub

跨 coding harness 的统一通信基础库。提供 TypeScript 库、本地 HTTP/SSE 服务、fetch SDK、JSON CLI 和 MCP 入口,连接已经运行的 Codex、Claude Code 会话。

English · 接口 · 设计 · 验证 · 豆包接入 · 待办清单

下一步设计:Agent 自动接入与最小感知协作(正式套件尚未实现;原生身份、双向收发及安装/生命周期已有隔离原型证据)。

当前实现

| 能力 | Codex | Claude Code | | ---------------- | ---------------------------------- | ---------------------------------------------------------- | | 发现与搜索 | 原生持久会话列表和搜索 | claude agents --json 运行中会话;名称/目录搜索 | | 历史 | 原生条目分页 | 本地日志分页与搜索,包含忙碌时的 peer 附件 | | 外部消息 | turn/start.toolOutput | 原生 inbox;2.x 且不低于 2.1.317,实验性适配,需要显式开启 | | 关联回复 | 会话所有者注册 agenthub_reply | 原生 SendMessage 返回 Hub socket | | 审批交互 | 库/HTTP 显式回答 | 当前适配器不支持 | | 任意会话实时订阅 | 不支持;依赖连接已有的原生监听关系 | 不支持;仅自身消息回调 |

统一接口明确区分 tool_output 和 peer_message,不会静默转换成用户输入。读取和发送均不自动启动、恢复、中断或重启会话,也不修改 Claude 的接收策略和权限。

原 Codex Session Bridge 的源码、22 个接口、SDK、OpenAPI、中英文文档及测试完整保留在 vendor/codex-bridge。原生生命周期和用户输入接口由独立的 codex-session-bridge 命令及 @gxcsoccer/agenthub/codex-bridge 导出保留。来源及许可证。

安装发布包

通过 npm 安装 CLI,需要 Node.js 22.13 或更新版本:

npm install -g @gxcsoccer/agenthub
agenthub --help

0.4.0 新增所有者断开与恢复、消息列表与清空,以及面向嵌入方的 Codex 和 Claude 选项。升级前请停止 Hub 并备份状态目录,连接器进程需与 Hub 同步升级。连接器状态升至版本 4,回滚需要该备份;从 0.1.0 升级仍需遵循迁移说明。

启动

需要 Node.js 22.13+,以及已运行的 Codex App Server 和/或 Claude Code。真实验证平台为 macOS;Windows 客户端、ACP 及实验性单向 pipe 的范围见扩展说明。

npm ci
npm run build
npm link
agenthub serve --config examples/local.json

示例配置显式开启 Claude 原生发送。不传配置时,Claude 默认只提供发现/历史,发送关闭。Codex 按需连接已有 control socket。服务绑定 127.0.0.1:3211,私有令牌保存在 ~/.agenthub/token,终端仅显示路径。

agenthub doctor
agenthub instances
agenthub sessions --harness claude
agenthub sessions --harness codex --search AgentHub
agenthub send --message-file /absolute/path/message.json
agenthub status --message-id MESSAGE_UUID --wait-ms 30000

消息文件格式如下,实际使用前替换目标 ID,并为新消息生成 UUID:

{
  "messageId": "95054348-8959-413e-89a3-3b98eab598d5",
  "to": { "harness": "claude", "instance": "local", "sessionId": "TARGET_SESSION_UUID" },
  "origin": { "name": "my-app" },
  "delivery": "peer_message",
  "text": "请检查接口方案,并返回关联回复。"
}

相同消息 ID 和相同载荷复用一次提交;不同载荷会冲突。transport_written 和 accepted 不表示模型已读。replied 才表示收到了关联回复;不确定投递保留为 unknown,不自动重发。

只读接入诊断

agenthub doctor
agenthub doctor --harness codex --session-id SESSION_ID
agenthub doctor --harness claude --instance local --timeout-ms 10000

doctor 复用现有服务与令牌,只调用 GET。默认检查认证及实例发现;指定会话时检查发送能力和回复前置条件,区分缺少工具、需要 attach、未开启 Claude 发送、版本不匹配及 inbox 不可用。输出 JSON,退出码为 0 通过、2 提醒、1 错误。每个 HTTP 请求默认超时 10 秒;最多检查 32 个实例,并发 4,每个只读取一页 10 条样本,不是全量会话清单。

它不发送探测消息、不建立回调、不检查磁盘写入,也不能证明模型已收到消息或当前 Claude 接收策略。报告省略会话名称、工作目录、正文及原始后端错误。SDK 可使用 client.doctor({ scope: { harness: 'codex', instance: 'local' }, sessionId });SDK 请求超时沿用客户端配置(默认 70 秒)。

基础库与回复路由

import { AgentHub, CodexAdapter, ClaudeAdapter } from '@gxcsoccer/agenthub';

const hub = new AgentHub([
  new CodexAdapter({ instance: 'local' }),
  new ClaudeAdapter({ instance: 'local', nativeMessaging: true }),
]);
try {
  console.log(await hub.listSessions({ harness: 'claude', instance: 'local' }));
} finally {
  await hub.close();
}

其他应用使用 @gxcsoccer/agenthub/client 中的 AgentHubClient 访问本地服务;该导出仅依赖 fetch。CLI/MCP 共用守护进程中的回执和回调监听。

消息可指定 replyTo,将第一条关联回复转发到指定会话。转发有独立消息 ID,保留 inReplyTo,增加跳数,以 messageKind: "result" 投递,不再提供回复模板或回复路由;结果回执保留投递证据,不等待 replied。0.2.0 包含此行为。原回执包含 forwardedMessageId 和可能的 forwardError。

Codex 回复需要所有者在创建会话时注册导出的 codexReplyTool。getSession() 返回 replyReadiness:ready、needs_attach、missing_tool、unknown 或 unavailable。工具注册根据本地会话元数据核验;日志尚未持久化或无法读取时保持 unknown。发送和重连不自动建立监听。断连或 Hub 重启后,所有者可显式执行下面的 attach:仅接受已加载、工具已核验的根会话,不传配置覆盖;调用方明确接受 loaded 检查与上游 thread/resume 之间发生卸载可能恢复会话的竞态。不能动态为任意已有会话安装工具。

agenthub attach-reply --harness codex --session-id SESSION_ID --accept-resume-race

守护进程默认将回执、载荷哈希、回复路由和回调关联持久化到令牌文件旁的 state.sqlite。用 --state-file FILE / AGENTHUB_STATE_FILE 修改位置,--ephemeral 关闭持久化。基础库可使用 await openLocalHub(config, { stateFile: absolutePath }),或将 await openReceiptStore(absolutePath) 传给 new AgentHub(adapters, { store }) 后等待 hub.ready();直接构造且不传 store 仍为内存模式。状态包含明文消息和回复,目录要求 0700,数据库和锁文件为 0600。

豆包与 MCP

env -u AGENTHUB_TOKEN agenthub mcp --origin-name 'Doubao Work' \
  --url http://127.0.0.1:3214 --token-file /ABS/PRIVATE/caller.token

MCP 使用官方 SDK,提供会话发现、详情、历史、消息提交和状态查询、全文检索共七个工具。面向 agent 的工具不开放审批、恢复或中断操作。配置模板。

0.3.0 的豆包接入提供目标选择、私有配置生成、Hub 生命周期和可选 CLI 插件。agenthub setup 支持通过显式 CDP 端口自动登记豆包 2.35.15 连接器。真实豆包 STDIO 对话已显示 Claude/Codex 回复;自动创建/移除另通过 5 项检查。豆包原生身份与主动唤醒仍未实现。

验证与边界

npm run check
npm run smoke:isolated -- --run --default-inbox --matrix
npm run smoke:recovery -- --run

真实 smoke 只操作新建且在 allowlist 中的会话,验证 Codex → Claude → Codex 及原生历史身份。测试后停止 Claude、归档并卸载 Codex;私有报告位于忽略的 .local/verification/。完整范围。

  • 持久回执保留 24 小时、最多 10,000 条;提交中断后重启转为 unknown,不自动重发。Claude 迟到回复可回到原回调地址;Codex 需要显式重新 attach。不保证 exactly-once。
  • 事件最多保留 2,000 条 / 4 MiB;重启或游标过期会明确报错。
  • Claude 只校验当前安装的 CLI 版本,无法认证每个已运行进程的版本。协议可能随版本变化。
  • 本地回调以同一 OS 用户为信任边界;来源字段不是经过认证的远程 agent 身份。
  • Claude 历史读取上限为日志 64 MiB、单条 2 MiB;不提供全量归档会话索引或任意会话实时订阅。

MIT,保留原 Codex Bridge 署名。

新增权限、持久事件、全文检索、ACP 与 Windows 范围。

Claude/Codex 原生登记、共享协作操作、Codex MCP connect 及显式启用的 Claude CLI connect 已纳入 0.2.0;安装步骤和边界见连接器接入。Claude CLI 激活经原生消息和现有 Bash 权限完成,可能启动模型轮次;原生 MCP 外部 reload 仍未实现。