New:Introducing Socket Scanning for VS Code Marketplace Extensions.Learn more →
Get Started

harnessbrew

Package Overview
Dependencies
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

harnessbrew

A Git-native package manager for AI Agent assets.

Source
npmnpm
Version
0.5.2
Version published
Weekly downloads
4
33.33%
Maintainers
1
Weekly downloads
 
Created
Source

HarnessBrew

HarnessBrew 是面向 AI Agent 资产的 Git 包管理器。它的定位类似 Homebrew：通过 Git Tap 发现资产，通过 Formula 描述资产，通过 Cellar 与 Receipt 安装、升级和安全卸载资产。

HarnessBrew 不托管资产。个人、团队和第三方资产都保存在各自的 Git 仓库中，并使用完全相同的安装机制。

主要能力

  • 注册、更新和移除 Git Tap
  • 校验并搜索 skill、agent、workflow、instruction、prompt、MCP 和 adapter Formula
  • 解析依赖、循环、缺失项与冲突
  • 按 Git commit 将不可变内容安装到 Cellar
  • 链接到 OpenAI Codex 和 Claude Code
  • 以原生格式投递 Skill、Agent、Workflow、Prompt、Instruction 和 MCP
  • 支持 user/project scope，以及同一 Target 的多实例
  • 通过 Receipt 跟踪文件、配置键、受管区块所有权和 SHA-256 摘要
  • 使用 doctor 诊断并通过 relink 修复 Target 漂移
  • 检测可用升级，并在升级后保留 Agent target 链接
  • 使用 Harnessfile 和 lockfile 在不同设备上复现环境
  • 从 npm 安装并通过 GitHub Release 发布

安装

要求：Node.js 20 或更高版本，系统中可用 Git。

npm install --global harnessbrew
harnessbrew --version

也可以直接使用：

npx harnessbrew help

HarnessBrew 默认将受管状态保存到 ~/.harnessbrew。测试或隔离环境可以设置 HARNESSBREW_HOME。

快速开始

注册自己的资产 Tap：

harnessbrew tap add xiejinheng/agents git@github.com:xiejinheng/agent-assets.git

搜索并查看 Formula：

harnessbrew search review
harnessbrew search --kind skill --target openai-codex
harnessbrew info xiejinheng/agents/code-review

安装到 Cellar，并链接到 Codex：

harnessbrew install xiejinheng/agents/code-review \
  --target openai-codex

如果只希望保存到 Cellar，不写入 Agent 配置目录，可以省略 --target。

更新和升级：

harnessbrew update
harnessbrew outdated
harnessbrew upgrade code-review

安全卸载：

harnessbrew uninstall code-review

若受管文件或链接已被修改，HarnessBrew 会停止卸载。确认需要删除时可以显式传入 --force。

Homebrew 概念对应

HomebrewHarnessBrew
brewharnessbrew
TapGit 资产源仓库
Formula / CaskAgent 资产 Formula
Cellar按 Git commit 隔离的本地安装区
Link到 Codex、Claude Code 等 target 的链接
BrewfileHarnessfile
Receipt安装来源、文件摘要与所有权记录

创建 Tap

Tap 是普通 Git 仓库。推荐按资产集合建立 Tap，不需要为每个 skill 单独建立仓库。

my-agent-tap/
├── tap.json
├── skills/
│   └── code-review/
│       ├── formula.json
│       └── SKILL.md
├── workflows/
├── agents/
├── instructions/
├── prompts/
├── mcp/
└── adapters/

最小 tap.json：

{
  "schemaVersion": 1
}

Formula 的目录名称必须与 name 一致，目录类型必须与 kind 一致：

{
  "schemaVersion": 1,
  "name": "code-review",
  "kind": "skill",
  "description": "Review code changes with a consistent rubric.",
  "entry": "SKILL.md",
  "targets": ["openai-codex", "claude-code"],
  "dependencies": [
    "xiejinheng/agents/repository-guardrails"
  ],
  "conflicts": [],
  "tags": ["review", "quality"]
}

完整坐标为 <owner>/<tap>/<formula>。依赖和冲突必须使用完整坐标，以避免跨 Tap 名称歧义。

Git commit 是安装版本的唯一事实来源；Formula 不维护 .snapshots 或重复的 history。

MCP Formula 的入口是统一 JSON。stdio 配置使用 command、可选 args 和只包含环境变量名称的 envVars；HTTP 配置使用 transport: "http"、url、可选 bearerTokenEnvVar 与 headersFromEnv。HarnessBrew 不接受入口中的明文 env 密钥值。

adapter Formula 当前是可由 Git/Cellar 管理的扩展包，但内置 Target 不执行它。请使用不带 --target 的 install 保存；link 或 install --target 会明确拒绝，直到插件运行时接口开放。

Target

当前内置：

  • openai-codex
  • claude-code

可以在安装时指定 target：

harnessbrew install code-review --target openai-codex

Codex Skill 默认安装到 ~/.agents/skills，其他 Codex 配置使用 ~/.codex；Claude Code 使用 ~/.claude。Skill 以完整目录软链安装，因此 scripts/、references/ 和 assets/ 等相对资源会与 SKILL.md 一起生效。Workflow 和 Prompt 会被投影为带标准 frontmatter 的 Target Skill。Agent 则以统一 Markdown 作为源码：投递到 Codex 时确定性渲染为 .codex/agents/<name>.toml，投递到 Claude Code 时渲染为 .claude/agents/<name>.md。Instruction 在 Codex 的 AGENTS.md 中使用带所有权标记的受管区块，在 Claude Code 中链接为 .claude/rules/<name>.md；MCP 分别按 TOML 区块或 JSON 键合并。卸载这些共享配置不会覆盖用户内容。需要隔离安装时可使用：

harnessbrew install code-review \
  --target openai-codex \
  --target-root /path/to/sandbox/.codex

Target 支持用户级与项目级 scope；--project 会隐式选择 project scope。同一 Formula 可以同时存在于两个 scope，Receipt 会按实际目标路径分别记录操作：

harnessbrew link code-review --target openai-codex --scope user
harnessbrew link code-review --target openai-codex --scope project --project /path/to/repo
harnessbrew unlink code-review --target openai-codex --scope project --project /path/to/repo

项目级 Codex 资产使用项目中的 .agents/skills、.codex/agents、根 AGENTS.md 和 .codex/config.toml；Claude Code 使用 .claude/skills、.claude/agents、.claude/rules 和根 .mcp.json。当同一 Target 有多个实例时，unlink 必须指定 scope。

harnessbrew doctor [formula] 会校验 Cellar 文件摘要和每条 Target operation，区分目标缺失与被修改；harnessbrew relink <formula> 会在 Cellar 完整的前提下，按 Receipt 记录的 scope/root 强制重建 HarnessBrew 拥有的目标。可用 --target、--scope 和 --project 只修复一个实例。

也可以单独管理链接：

harnessbrew link code-review --target openai-codex
harnessbrew unlink code-review --target openai-codex

Harnessfile

Harnessfile 适合提交到个人 dotfiles 或项目仓库：

schemaVersion: 1
taps:
  - name: xiejinheng/agents
    git: git@github.com:xiejinheng/agent-assets.git
    ref: main

assets:
  - formula: xiejinheng/agents/code-review
    targets: [openai-codex]

安装并生成 Harnessfile.lock：

harnessbrew bundle install

lockfile 会记录每个 Tap 的准确 commit、依赖闭包和 target，应与 Harnessfile 一起提交到 Git。

在其他设备运行同一命令时，HarnessBrew 会检出 lockfile 固定的 commit，而不是未经确认地使用 Tap 最新版本。

清理清单之外的受管资产：

harnessbrew bundle cleanup

使用其他文件路径：

harnessbrew bundle install --file ./config/Harnessfile

CLI

harnessbrew tap add <owner/name> <git-url> [--ref <ref>]
harnessbrew tap list
harnessbrew tap update [owner/name]
harnessbrew tap remove <owner/name>
harnessbrew untap <owner/name>
harnessbrew search [query] [--kind <kind>] [--target <target>]
harnessbrew info <formula>
harnessbrew install <formula> [--target <target>] [--scope <user|project>] [--project <path>] [--target-root <path>]
harnessbrew list
harnessbrew link <formula> --target <target> [--scope <user|project>] [--project <path>] [--target-root <path>]
harnessbrew unlink <formula> --target <target> [--scope <user|project>] [--project <path>] [--force]
harnessbrew doctor [formula]
harnessbrew relink <formula> [--target <target>] [--scope <user|project>] [--project <path>]
harnessbrew update
harnessbrew outdated
harnessbrew upgrade [formula]
harnessbrew uninstall <formula> [--force]
harnessbrew bundle install [--file <path>]
harnessbrew bundle cleanup [--file <path>]

本地目录

~/.harnessbrew/
├── taps/       # HarnessBrew 管理的 Git 工作树
├── cellar/     # 按 Formula 与 commit 隔离的不可变内容
├── receipts/   # 安装、依赖、target 链接和摘要
└── state.json  # Tap 注册状态

Tap 工作树和 Cellar 内容都由 HarnessBrew 管理，不应直接编辑。个人资产应在原始 Tap 仓库中修改、提交和推送，再通过 update/upgrade 安装。

安全边界

  • Formula 是声明式 JSON；HarnessBrew 不执行 Tap 中的任意脚本。
  • Formula 入口不能逃逸所属目录。
  • 安装前会检查依赖、冲突和 target 兼容性。
  • HarnessBrew 不覆盖未由 Receipt 管理的目标文件。
  • 卸载前会检查 Cellar 文件摘要和符号链接目标。
  • 私有 Tap 凭据由系统 Git/SSH credential 机制管理。

开发

项目使用 TypeScript 7.0，并启用严格类型检查。

npm ci
npm run build
npm test
npm run check

npm run check 会执行 TypeScript 编译、全部 Node.js 测试、安装包冒烟测试和 npm pack --dry-run。

架构

完整设计见 docs/architecture.md。

License

MIT

Keywords

agent
assets
skills
instructions
git
package-manager

FAQs

Package last updated on 12 Aug 2026

Related posts

Malicious Firefox Extensions Impersonate Phantom, Jupiter, and Bitget to Steal Wallet Secrets

Threat Research

Malicious Firefox Extensions Impersonate Phantom, Jupiter, and Bitget to Steal Wallet Secrets

Malicious Firefox extensions mimic Phantom, Jupiter, and Bitget wallets to steal recovery phrases and private keys, with one fetching its payload remotely.

By Kush Pandya  -  Oct 27, 2026