cc-buddy-forge (ccbf)

通过暴力搜索 salt 值，锻造你理想中的 Claude Code 宠物伴侣。

Claude Code 的 buddy 系统通过 hash(userId + SALT) 确定性地生成宠物属性。本工具可以搜索数百万个 salt 值，找到能产生你梦想宠物的组合，然后一键应用到本地 Claude Code 二进制文件中。

安装

# npm 全局安装
npm install -g cc-buddy-forge
ccbf --help

如果安装时遇到权限不足，可以改用：

sudo npm install -g cc-buddy-forge

这种方式会先安装一个很小的 Node 启动器，然后在 postinstall 阶段自动从 GitHub Releases 下载对应平台的预编译 ccbf 二进制。 该安装方式要求本机 Node 版本不低于 18。 当前 npm 预编译安装支持：macOS arm64/x64、Linux x64、Windows x64。 你也可以从 GitHub Releases 下载对应平台的压缩包，解压后将 ccbf 放到你的 PATH 中。 如果在 Windows 上自动检测不到 Claude Code 二进制，可以显式传入 --binary C:\\path\\to\\claude.exe。

本地开发安装

# 前置条件：Bun >= 1.0
# https://bun.sh

# 克隆并安装
git clone https://github.com/Snychng/cc-buddy-forge.git
cd cc-buddy-forge
bun install

# 注册全局 ccbf 命令
bun link

# 开始使用
ccbf --help

命令

ccbf search — 搜索理想宠物

搜索符合目标属性的 salt 值。Salt 长度会自动从已安装的 Claude Code 二进制文件中检测。 如果你的 Claude Code 是通过 npm 安装，或者自动探测失败，建议先运行 ccbf doctor 查看 ccbf 实际解析到了哪个目标文件。

# 搜索传说级龙（默认搜索 100 万次）
ccbf search --species dragon --rarity legendary

# 搜索任意闪光宠物
ccbf search --shiny

# 搜索高混乱值的史诗级猫
ccbf search --species cat --rarity epic --min-stat CHAOS:80

# 加大搜索量以寻找稀有组合
ccbf search --species dragon --rarity legendary --shiny --total 10000000

# 手动指定 userId
ccbf search --species owl --rarity rare --user-id "your-user-id"

可用过滤条件：

| 参数 | 可选值 | |------|--------| | --species | duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk | | --rarity | common (60%), uncommon (25%), rare (10%), epic (4%), legendary (1%) | | --eye | · ✦ × ◉ @ ° | | --hat | none, crown, tophat, propeller, halo, wizard, beanie, tinyduck | | --shiny | 1% 概率，无需传值 | | --min-stat | DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK（格式：名称:数值） | | --total | 搜索次数（默认：1000000） |

ccbf patch — 直接修补二进制

直接修补已安装的 Claude Code 二进制文件，无需源码或重新构建。适用于通过 install.sh 安装的用户。 在 macOS 上，ccbf 会在修改后二进制自动执行 ad-hoc 重签名，避免 Claude Code 因 SIGKILL (Code Signature Invalid) 无法启动。 首次运行或首次修补时，ccbf 会自动记录该二进制的原始 salt，后续可直接用 ccbf restore 一键恢复。

# 使用搜索结果中的 salt 进行修补
ccbf patch --salt "ccbf-0000000088"

# 指定自定义二进制路径
ccbf patch --salt "ccbf-0000000088" --binary /path/to/claude

ccbf restore — 恢复原始 salt

使用首次运行或首次修补时保存的快照，自动恢复 Claude Code 二进制文件中的原始 salt。 在 macOS 上，恢复后的二进制同样会自动重新签名。

# 自动恢复原来的宠物
ccbf restore

# 恢复指定 Claude 二进制
ccbf restore --binary /path/to/claude

ccbf preview — 预览宠物

查看当前宠物，或预览使用其他 salt 后的效果。

# 查看当前宠物
ccbf preview

# 预览指定 salt 的宠物
ccbf preview --salt "ccbf-0000000088"

ccbf doctor — 检查二进制定位

输出 ccbf 当前解析到的 Claude Code 目标路径、推断安装方式，以及该路径是否成功检测到 salt。 当 search / patch / restore 报错 Could not detect salt in Claude Code binary 时，先运行这个命令排查。

# 自动检查当前 Claude Code 安装
ccbf doctor

# 检查一个显式传入的 wrapper 或二进制路径
ccbf doctor --binary /path/to/claude

如果 ccbf doctor 显示你的 PATH 命中了 wrapper，或者命中了 npm 安装的 Claude Code 入口，可以直接把它解析出的真实目标路径再传给 search / patch：

ccbf search --binary /path/to/real/claude
ccbf patch --binary /path/to/real/claude --salt "ccbf-0000000088"

工作原理

1. Claude Code 通过 mulberry32(hash(userId + SALT)) 生成宠物属性
2. SALT 硬编码在 Claude Code 二进制文件中
3. ccbf search 自动检测当前 salt 长度，生成完全等长的候选 salt
4. 每个不同的 salt 会产生完全不同的宠物 — 物种、稀有度、属性值全部重新生成
5. ccbf patch 在二进制中进行安全的逐字节替换（等长 = 不破坏结构）
6. ccbf 会将原始 salt 保存到 ~/.ccbf.json，因此后续恢复只需要一条命令

二进制修补

适用于通过 curl -fsSL https://claude.ai/install.sh | bash 安装的用户：

• ccbf search 自动从已安装的二进制文件中检测 salt 并生成匹配长度的 salt
• ccbf patch 原地替换 salt — 无需源码、无需重新构建、无需重新编译
• ccbf restore 随时恢复已记录的原始 salt
• 安全的逐字节替换：新 salt 始终与原始 salt 完全等长
• 在 macOS 上，修补/恢复后二进制会自动执行 ad-hoc 重签名

性能

Apple Silicon 上典型搜索速度：约 1,000,000 次/秒。100 万次搜索约 1 秒完成。

| 目标 | 每 100 万次预期匹配数 | |------|----------------------| | 指定物种 | ~55,000 | | 传说级 | ~10,000 | | 传说级 + 指定物种 | ~550 | | 闪光 | ~10,000 | | 闪光 + 传说级 | ~100 | | 闪光 + 传说级 + 指定物种 | ~5 |

项目结构

src/
  index.tsx          # CLI 入口（commander）
  core/
    types.ts         # 物种、稀有度、属性类型与常量
    roller.ts        # PRNG（mulberry32）+ 哈希 + roll 逻辑
    search.ts        # 暴力搜索引擎
    sprites.ts       # 18 种物种的 ASCII 艺术图
    apply.ts         # Salt 替换（二进制修补）
  tui/
    PetCard.tsx      # 宠物预览卡片（精灵图 + 属性）
    SearchView.tsx   # 搜索进度 + 结果展示
    PreviewView.tsx  # 当前 vs 预览对比
  utils/
    config.ts        # userId 自动检测
    state.ts         # 原始 salt 快照存储

开发

# 直接运行
bun run src/index.tsx preview

# 通过 npm scripts 运行
bun run search    # 等同于：bun run src/index.tsx search
bun run preview   # 等同于：bun run src/index.tsx preview

# 类型检查
bun run tsc --noEmit

发布流程

1. 更新 package.json 中的版本号。
2. 推送类似 v1.2.3 的 tag。
3. GitHub Actions 会构建 macOS arm64/x64、Linux x64 与 Windows x64 二进制，创建 GitHub Release，并上传 checksum 与 manifest.json。
4. 如果仓库配置了 NPM_TOKEN secret，同一个工作流还会在 Release 产物上线后自动发布 cc-buddy-forge 到 npm。

注意事项

• 需要 Bun（不支持 Node）— 哈希函数使用 Bun.hash 以确保与 Claude Code 完全一致
• userId 自动从 ~/.claude.json 或 ~/.claude/.config.json 读取
• 原始二进制 salt 会保存在 ~/.ccbf.json
• 仅修改本地安装，不影响其他用户
• patch 命令会修改自动检测到的本地 Claude Code 二进制；在 macOS / Linux 上通常位于 ~/.local/share/claude/versions/
• npm 安装当前支持的平台与 GitHub Releases 保持一致：macOS arm64/x64、Linux x64、Windows x64
• 如果 Claude Code 是通过 npm 安装，PATH 可能先命中 wrapper；此时建议先运行 ccbf doctor，必要时再把解析出的真实目标路径传给 --binary
• 如果 Windows 上 PATH 命中了 claude.cmd 之类的包装器，仍可通过 --binary C:\\path\\to\\claude.exe 指向真实二进制
• 如果要通过 GitHub Actions 自动发布 npm，需要在仓库 secrets 中配置 NPM_TOKEN