Kibitz

Kibitz 是一个 VS Code 扩展 + CLI（命令行界面）工具，用于监视 Claude/Codex 会话，生成实时评论，并允许你从一个 composer（编辑器）向现有或新会话发送提示词。

安装

VS Code 扩展 — 从 VS Code Marketplace 安装，或在扩展面板中搜索 Kibitz。

CLI — Homebrew（macOS / Linux）

brew install kibitzsh/tap/kibitz

CLI — npm

npm install -g @kibitzsh/kibitz

兼容性矩阵（合约）

平台	VS Code 面板	终端 CLI
macOS	支持	支持
Windows	支持	支持
Linux	尽力支持	尽力支持

核心功能

• 为 Claude Code 和 Codex 会话提供实时评论流。
• 跨会话提示词分发：
  • 现有活动会话。
  • 当前提供商的新会话。
• Composer 中的斜杠控制：
  • /help、/pause、/resume、/clear、/focus、/model、/preset、/interval、/update
  • 会话目标指定如 /1、/2
• 提供商感知的模型处理。
• 严格的分发状态事件：queued（已排队）、started（已开始）、sent（已发送）、failed（失败）。

提示词分发

Kibitz 可以向任何活动的受监视会话（Claude 或 Codex）发送提示词，或在当前提供商上启动新会话。

VS Code 面板

• 目标徽章始终包含：
  • /1 New session (current provider)（新会话，当前提供商）
  • /2..N 来自监视列表的现有活动会话
• 启动新终端会话只需一步：选择 /1 并发送你的提示词。
• 通过以下方式选择目标：
  • 点击目标徽章
  • 输入 /N（仅选择）
  • 输入 /N <prompt> 或 N/ <prompt>（选择 + 发送）
• 纯文本（无目标令牌）发送到当前选定的目标。
• 每次发送都会发出明确的状态更新：queued、started、sent、failed。

终端 CLI

• 使用 /sessions 列出带有数字索引的活动会话。
• 使用 /target <index|agent:sessionId|new-codex|new-claude> 设置目标。
• 使用 /interval <15s|30s|1m|5m|15m|1h> 设置摘要频率。
• 使用 /update 检查更新。
• 启动新终端会话只需一个命令：/target new-codex（或 /target new-claude），然后发送纯文本。
• 选择目标后，纯文本将发送到该目标。
• 每次发送都会打印分发状态：queued、started、sent、failed。

范围和限制

• 目标限定于监视窗口中的活动会话（近期活动）。
• 单次发送的多目标广播功能尚未实现。

开发环境设置

前置要求

• Node.js 20+
• npm 10+
• VS Code 1.85+
• 至少安装并认证一个提供商 CLI：
  • codex / codex.cmd
  • claude / claude.cmd

构建

npm ci
npm run build

部署到本地 VS Code/Cursor

npm run deploy:vscode

此命令将 dist/ 和 package.json 复制到你的本地扩展目录，并替换旧的 Kibitz 扩展文件夹。

运行 CLI

npm run build
node dist/cli/index.js

测试

npm run typecheck
npm run check:compat
npm run test:ui
npm run test:download-digest
npm run test:all

有用的针对性检查：

npm run test:parsers
npm run check:session-names
npm run check:model-persistence

发布流程

1. 本地冒烟测试和打包：
   • npm run deploy:vscode（本地安装到 VS Code/Cursor）
   • npm run package（构建 .vsix）
2. 完整的受保护发布流程：
   • npm run cr
3. npm run cr 执行检查/构建、版本升级、发布到 VS Code Marketplace 和 npm、验证版本、更新 Homebrew 公式，并推送标签。
4. 如需在标签推送时自动触发 GitHub 发布，请添加仓库密钥：
   • VSCE_PAT（VS Marketplace 发布 PAT，个人访问令牌）
   • NPM_TOKEN（npm 发布令牌）
   • HOMEBREW_TAP_TOKEN（具有 kibitzsh/homebrew-kibitz 写入权限的 GitHub 令牌）
5. 如需每日下载摘要邮件工作流（.github/workflows/release-download-digest.yml），请添加：
   • RESEND_API_KEY（Resend API 密钥）
   • HOMEBREW_TAP_TOKEN（具有 kibitzsh/homebrew-kibitz 流量 API 读取权限的 GitHub 令牌）
   • 发件人固定为 stats@kibitz.sh
   • 收件人固定为 vasilytrofimchuk@gmail.com

每日下载摘要邮件

• 工作流：.github/workflows/release-download-digest.yml
• 脚本：scripts/download-digest.js
• 计划：每日太平洋时间上午 9:00（UTC cron + PT 小时守卫）
• 发件人：stats@kibitz.sh
• 收件人：vasilytrofimchuk@gmail.com
• 数据来源：
  • VS Marketplace downloadCount（下载计数）for kibitzsh.kibitz
  • GitHub Releases 资源 download_count（下载计数）for kibitzsh/kibitz
  • npm 范围总下载量 for @kibitzsh/kibitz
  • Homebrew tap 克隆流量代理 from kibitzsh/homebrew-kibitz (/traffic/clones)
• 状态缓存文件：.cache/download-digest/state.json
• 行为：
  • 首次运行初始化基线（不发送邮件），
  • 零增量日期跳过邮件，
  • 正增量发送摘要邮件。
• 手动运行：
  • GitHub Actions → Daily Download Digest → Run workflow
• 本地冒烟测试（真实发送）：

  RESEND_API_KEY=... \
  RESEND_FROM_EMAIL=stats@kibitz.sh \
  ALERT_EMAIL_TO=vasilytrofimchuk@gmail.com \
  HOMEBREW_TAP_TOKEN=... \
  ENFORCE_9AM_PT=0 \
  DOWNLOAD_DIGEST_STATE_FILE=/tmp/kibitz-digest-test-state.json \
  node scripts/download-digest.js
  

分发渠道

1) VS Code 扩展市场

• 在 VS Marketplace 创建发布者（如尚未创建）。
• 创建具有 Marketplace 发布范围的 Azure DevOps PAT（个人访问令牌）。
• 使用 npm run publish:vscode 发布（需要 VSCE_PAT）。
• 建议：
  • 向 Marketplace 发布稳定版本，
  • 在 GitHub Releases 中保留 .vsix 工件以供手动安装/回滚。

2) OpenVSX（适用于 Cursor/VSCodium 生态系统）

• 将相同的扩展包发布到 OpenVSX。
• 与 Marketplace 保持版本一致。

3) npm（CLI 分发）

• 保持 bin.kibitz 指向 dist/cli/index.js。
• 将包发布到 npm。
• 用户可以全局安装并运行 kibitz。

4) Homebrew

两种常见路径：

• 从 npm 安装的公式：
  • 包装 npm install -g kibitz。
• 下载构建好的 tarball/二进制文件并安装启动器的 tap 公式。

对于 VS Code 扩展，Homebrew 是可选的，通常次于 Marketplace/OpenVSX。

5) GitHub Releases

• 每个版本上传 .vsix 和变更日志。
• 添加快速安装说明：
  • code --install-extension <file>.vsix

推荐分发渠道栈

对于大多数用户，建议按以下顺序选择：

1. VS Marketplace（VS Code 主要安装途径）
2. OpenVSX（次要生态系统覆盖）
3. npm（CLI 用户）
4. GitHub Releases（.vsix 构建产物 + 发布说明）

仅当您的 CLI 安装需求较高，且希望在 macOS/Linux 上一键完成设置时，再添加 Homebrew。

文档

• 支持矩阵详情
• 兼容性发布检查清单

法律信息

• 许可证 (MIT)
• 隐私政策
• 使用条款

跨平台说明

Kibitz 借鉴了经过验证的 room 模式：

• macOS 上继承登录 shell 的 PATH 环境变量。
• Windows 上增强 npm 全局前缀的 PATH 环境变量。
• Windows .cmd 命令映射（claude.cmd、codex.cmd）。
• 平台参数化的兼容性测试。

Kibitz 快速上手指南

环境准备

系统要求

平台	VS Code 面板	终端 CLI
macOS	✅ 支持	✅ 支持
Windows	✅ 支持	✅ 支持
Linux	⚠️ 尽力支持	⚠️ 尽力支持

前置依赖

• Node.js 20+
• npm 10+
• VS Code 1.85+
• AI 工具 CLI（至少安装并登录一个）：
  • claude / claude.cmd（Claude Code）
  • codex / codex.cmd（OpenAI Codex）

---

安装步骤

方式一：VS Code 扩展（推荐）

1. 打开 VS Code，进入扩展面板（Ctrl+Shift+X / Cmd+Shift+X）
2. 搜索 Kibitz 并安装
3. 或访问 VS Code Marketplace 在线安装

方式二：CLI 命令行工具

macOS / Linux（Homebrew）

brew install kibitzsh/tap/kibitz

npm（跨平台）

npm install -g @kibitzsh/kibitz

---

基本使用

VS Code 面板操作

启动新会话并发送提示

1. 打开 Kibitz 面板
2. 点击 /1 New session (current provider) 或输入 /1
3. 直接输入提示内容发送

向现有会话发送提示

• 点击目标会话徽章（如 /2、/3）
• 或输入 /2 <你的提示> 快速选择并发送

常用快捷指令

指令	功能
/help	显示帮助
/pause / /resume	暂停/恢复监听
/clear	清空面板
/focus	聚焦当前会话
/model <模型名>	切换模型
/interval <15s|30s|1m|5m|15m|1h>	设置摘要频率

终端 CLI 操作

查看活跃会话

/sessions

启动新会话

/target new-claude    # 启动 Claude 新会话
/target new-codex     # 启动 Codex 新会话

切换到现有会话

/target 2             # 按索引切换
/target agent:abc123  # 按会话 ID 切换

设置摘要频率

/interval 1m

发送提示 设置目标后，直接输入文本即可发送。

---

状态说明

每次发送提示后，系统会返回明确状态：

• queued — 已排队
• started — 已开始处理
• sent — 已发送成功
• failed — 发送失败