Use a package's harness
In short
- After
npx harnesspm init, every full install gives your agents the harness of the versions you installed. - Your agents read rules and pointers in
AGENTS.md, and skills, sub-agents and tools in their own folders. - Upgrades show up in pull requests as changes to the managed block and the lock.
Set the project up first with Set up a project.
harnesspm reads the dependencies, devDependencies and optionalDependencies of your project. Each one that has a harness/ folder is a harness package. A package also brings the harness of the packages it lists in extends. Nothing else reaches you: a library’s own development tools never do.
harnesspm only reads files. It never runs code from a package to find its harness.
| Unit | How the agent gets it |
|---|---|
| Always-on rule | Its text is in the managed block in AGENTS.md. |
| File-scoped rule | A pointer line in the block. Claude Code also loads it by itself when it works on a matching file. |
| On-demand rule | A pointer line with a description. The agent reads it when it is relevant. |
| Docs | One pointer line to an index of the package’s docs, at the installed version. |
| Skill | A link in .claude/skills/ and .agents/skills/. The agent loads it when it fits the task. |
| Sub-agent | A file in .claude/agents/ and .codex/agents/. |
| Script | A line in the block with the command that runs it, once the package is trusted. |
| Hook, MCP server, permission | Entries in each agent’s settings, once the package is trusted. |
Every line in the block ends with the unit’s ID, such as acme-colors:rules/usage. npx harnesspm why <ID> finds its source. The package format lists every kind.
Package managers put packages in different places. harnesspm links each harness package to one stable path in node_modules/.harnesspm/pkgs/, and the block uses only these paths. So the same block works on every machine and with every package manager.
A job that does not install dependencies, such as a review bot, runs npx -y @tenphi/harnesspm fetch. It downloads only the harness packages in the lock, checks their integrity, and fills the same paths. The lock takes each package’s integrity from package-lock.json, pnpm-lock.yaml or Yarn 1’s yarn.lock. With Yarn 4, fetch downloads without that check and says so for each package.
- A full install (
npm install,npm ci,pnpm install,yarn) runsharnesspm syncfor you. npm install <pkg>,npm uninstall <pkg>,pnpm add <pkg>andpnpm remove <pkg>run no scripts. Runnpx harnesspm syncafter them.- Yarn 4 runs
postinstallbut notprepare. In a published package, whereinitusesprepare, runyarn harnesspm syncafter installs. See package managers.
The pull request shows the change. The block names each package’s version, and the lock records every unit’s hash:
-## @acme/ui 4.2.0
+## @acme/ui 4.3.0When an upgrade changes a section that your patch replaces or removes, sync warns and names the section, because your patch may be out of date.
The block points at one path per package, so harnesspm uses one version of each package in a repository. A direct dependency wins. Otherwise the copy closest to your project in the extends chain wins, then the highest version. harnesspm warns and names the versions. See one package, several versions.
Always-on text is in every session. npx harnesspm status reports its size for each agent:
📏 always-on Codex 2.5 KiB of 32 KiB · Claude Code 61 linesCodex reads AGENTS.md files up to 32 KiB by default and cuts off the rest. status warns when AGENTS.md comes close to that limit and says when it is over, and doctor warns too. Both also name each harnesspm block that Codex never reaches, such as one after long hand-written text. Move that block to the top of the file: sync keeps it there. Claude Code’s docs advise under about 200 lines per CLAUDE.md. Both facts have sources in agent capabilities. To drop a package or a unit you do not need, see Change upstream units.
- Resolution in the specification: layers,
extendsand priority. - Outputs in the specification: every file harnesspm writes for each agent.