Set up a project
In short
- Install
@tenphi/harnesspmas a dev dependency and runnpx harnesspm initonce. - Commit
AGENTS.md,CLAUDE.md,harnesspm.json,harnesspm.lock.json,package.jsonand the package manager’s lockfile. - Trust is the person’s decision. An agent asks first, and the person turns the tools on in their own terminal.
- Add
npx harnesspm sync --checkto CI.
You need Node.js 20 or later, and npm, pnpm, Yarn 1 or Yarn 4 with the node-modules linker. harnesspm writes files for Claude Code and Codex.
npm i -D @tenphi/harnesspm # or: pnpm add -D @tenphi/harnesspm
# or: yarn add -D @tenphi/harnesspmThe package is @tenphi/harnesspm. The command it installs is harnesspm, so npx harnesspm … works in the project from now on.
Do not skip this step. init adds a script that calls the harnesspm command, so it stops when the project does not list the package as a dependency.
The examples on this site use one app. It depends on @acme/ui, a design system that passes on the harness of @acme/colors and @acme/styles. The packages are made up, and the output is real:
$ npx harnesspm init
Created harnesspm.json
Added `harnesspm sync` to the "postinstall" script
CLAUDE.md now imports AGENTS.md
⏳ pending: @acme/colors: 1 script (not trusted; a person turns it on in "trust" in harnesspm.json)
⏳ pending: @acme/styles: 1 script, 1 hook (not trusted; a person turns it on in "trust" in harnesspm.json)
⏳ pending: @acme/ui: 1 script (not trusted; a person turns it on in "trust" in harnesspm.json)
harnesspm: 6 rules, 5 skills, 4 docs from 4 packages. Updated 18 files.
To commit: AGENTS.md, CLAUDE.md, harnesspm.json, harnesspm.lock.json, package.json, package-lock.json
Links and settings for this machine stay out of git: .git/info/exclude lists them.init does four things:
- It creates
harnesspm.json, the project’s configuration. Every field is optional. - It adds
harnesspm synctopostinstallin a private package, or topreparein a published one. Every full install now runs it, and an install without dev dependencies skips it (step 5). - It makes
CLAUDE.mdimportAGENTS.mdwith an@AGENTS.mdline, so Claude Code reads the same rules as Codex. - It runs
harnesspm sync, which finds the harness of every dependency and writes each agent’s files.
The four packages are the three @acme packages and harnesspm itself. Its own harness teaches agents to use harnesspm, with the skills harnesspm-import, harnesspm-export and harnesspm-improve.
The pending lines are normal. They name who turns the tools on: a person, never the agent. Rules, docs and skills work at once. Scripts, hooks and MCP servers wait until you trust their package (step 4). A rule in the block may already name a script that is still off: npx harnesspm run refuses it until then.
A pending line gives only a count. To learn what each tool does, read the package’s manifest, node_modules/.harnesspm/pkgs/<package>/harness/plugin.json:
scriptshas each script’sdescription."allow": truemeans that the script asks to run without a prompt.- Hooks are in
harness/dev.harnesspm/hooks.json, and MCP servers inharness/mcp.json.
| File | What it holds | Commit |
|---|---|---|
AGENTS.md |
The managed block: always-on rules, a docs index and scripts for each package | Yes |
CLAUDE.md |
@AGENTS.md, so Claude Code reads the block. A folder with its own AGENTS.md that git tracks gets one too. |
Yes |
harnesspm.json |
Your configuration: trust, patches, exclusions | Yes |
harnesspm.lock.json |
Every harness package and every unit’s hash | Yes |
package.json |
The dev dependency, and the postinstall or prepare script |
Yes |
package-lock.json, pnpm-lock.yaml or yarn.lock |
The dev dependency, as your package manager locked it | Yes |
.claude/, .agents/, .codex/, node_modules/.harnesspm/ |
Links and settings for each agent | No. harnesspm lists them in .git/info/exclude. |
git add AGENTS.md CLAUDE.md harnesspm.json harnesspm.lock.json package.json package-lock.json
git commit -m "chore: set up harnesspm"If your repository has AGENTS.md files in subfolders, also commit the CLAUDE.md that sync wrote next to each. Claude Code skips a nested AGENTS.md once the root has a CLAUDE.md, and the import brings it back.
harnesspm never edits .gitignore. Text outside the managed block in AGENTS.md stays yours. See what is committed.
A package can ship scripts, hooks and MCP servers. They run only when your project trusts the package.
Trust is the person’s decision, in two steps:
- The package goes into
trustinharnesspm.json. The person edits the file, or tells an agent which packages to add. An agent never adds one by itself. - The person runs
npx harnesspm approvein their own terminal. It writes the new hooks, MCP servers and allow rules. When an agent runssync, these stay pending, andapproverefuses an agent.
Step 1 looks like this:
{
"$schema": "https://unpkg.com/@tenphi/harnesspm/schema/harnesspm.schema.json",
"trust": { "@acme/ui": true }
}After step 2, the script of @acme/ui appears in the block:
- Script: `npx harnesspm run acme-ui:tokens` — Find a color token by a part of its name, with its light and dark values (acme-ui:scripts/tokens)@acme/ui asks for its script to run without a prompt, so harnesspm also writes an allow rule for it into .claude/settings.local.json and Codex’s rules. true follows upgrades. Use "pin" for a package your team does not control: each new version then waits for npx harnesspm approve. See Trust and safety.
- A full install, such as
npm install,npm ciorpnpm install, runssyncfor you. - After
npm install <pkg>,npm uninstall <pkg>orpnpm add <pkg>, no script runs. Runnpx harnesspm syncyourself. - After you edit
harnesspm.json, runnpx harnesspm sync. - An install without dev dependencies, such as
npm ci --omit=devin a Docker build, skips the sync, and the install goes on.
The script that init adds checks first that harnesspm is installed:
"scripts": {
"postinstall": "node -e \"try{require.resolve('@tenphi/harnesspm/package.json');process.exit(1)}catch{}\" || harnesspm sync"
}Leave it as it is. A plain harnesspm sync fails every install without dev dependencies, because the harnesspm command is not installed then. A project that an older harnesspm set up has that plain form: run npx harnesspm init again to update it. npx harnesspm doctor warns until you do. The install hook in the specification explains each part.
Add a check to CI, so a missed sync fails the pull request:
- run: npm ci
- run: npx harnesspm sync --check--check writes nothing and ignores harnesses that people added on their machines. The sync that npm ci runs does not hide a missed sync: with CI=true, it writes only per-machine files, such as links and docs indexes, and leaves the committed files for --check to compare. A job that commits the result runs npx harnesspm sync --write instead.
When something is out of date, --check says what to do:
$ npx harnesspm sync --check
❌ AGENTS.md: the harnesspm block is out of date
❌ harnesspm.lock.json is out of date
Run `npx harnesspm sync` and commit the result.status lists the layers, the packages and the always-on size for each agent:
$ npx harnesspm status
📦 dependencies @acme/ui 4.2.0 → @acme/colors 2.1.0, @acme/styles 3.4.1
🏢 project harnesspm.json: no changes
➕ added none
⏳ pending: @acme/colors: 1 script (not trusted; a person turns it on in "trust" in harnesspm.json)
⏳ pending: @acme/styles: 1 script, 1 hook (not trusted; a person turns it on in "trust" in harnesspm.json)
📏 always-on Codex 2.5 KiB of 32 KiB · Claude Code 61 linesdoctor checks that per-machine files stay out of git and that the outputs are in place. Each problem names the command that fixes it:
$ npx harnesspm doctor
🔒 Local files
✅ 15 per-machine files: ignored by git and not tracked
➕ Harnesses of your own
✅ .git/info/exclude can be written, so harnesspm keeps per-machine files out of git
ℹ️ No harness added yet. Add one with `npx -y @tenphi/harnesspm add <source>`.
📦 Outputs
✅ Committed outputs are up to date
✅ 20 per-machine outputs in place
🛡️ Trust
⚠️ Off: @acme/colors: 1 script (not trusted; a person turns it on in "trust" in harnesspm.json)
⚠️ Off: @acme/styles: 1 script, 1 hook (not trusted; a person turns it on in "trust" in harnesspm.json)
✅ Ready. Nothing to fix.why names the source of any unit, every change made to it, and how to change it yourself:
$ npx harnesspm why acme-colors:rules/usage
owner dependency @acme/colors 2.1.0 (via @acme/ui)
source node_modules/.harnesspm/pkgs/@acme/colors/harness/dev.harnesspm/rules/usage.md
patch node_modules/@acme/ui/harness/dev.harnesspm/patches/acme-colors-usage.patch.md (from @acme/ui)
repository https://github.com/acme/colors
editable no. Add a `patch`, `replace` or `exclude` in harnesspm.json, or propose the change upstream.- Use a package’s harness: what agents get, and upgrades.
- Change upstream units: patch, replace or exclude a rule.
- Share a harness from your library.
- Add your own or your team’s harness.