Skip to content
harnesspmv0.5.1
Color scheme
Contrast
Color scheme
Contrast

Set up a project

In short

  • Install @tenphi/harnesspm as a dev dependency and run npx harnesspm init once.
  • Commit AGENTS.md, CLAUDE.md, harnesspm.json, harnesspm.lock.json, package.json and 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 --check to 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.

1. Install

npm i -D @tenphi/harnesspm      # or: pnpm add -D @tenphi/harnesspm
                                # or: yarn add -D @tenphi/harnesspm

The 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.

2. Run init

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:

  1. It creates harnesspm.json, the project’s configuration. Every field is optional.
  2. It adds harnesspm sync to postinstall in a private package, or to prepare in a published one. Every full install now runs it, and an install without dev dependencies skips it (step 5).
  3. It makes CLAUDE.md import AGENTS.md with an @AGENTS.md line, so Claude Code reads the same rules as Codex.
  4. 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:

  • scripts has each script’s description. "allow": true means that the script asks to run without a prompt.
  • Hooks are in harness/dev.harnesspm/hooks.json, and MCP servers in harness/mcp.json.

3. Commit what it wrote

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.

4. Turn on a package’s tools

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:

  1. The package goes into trust in harnesspm.json. The person edits the file, or tells an agent which packages to add. An agent never adds one by itself.
  2. The person runs npx harnesspm approve in their own terminal. It writes the new hooks, MCP servers and allow rules. When an agent runs sync, these stay pending, and approve refuses 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.

5. Keep it current

  • A full install, such as npm install, npm ci or pnpm install, runs sync for you.
  • After npm install <pkg>, npm uninstall <pkg> or pnpm add <pkg>, no script runs. Run npx harnesspm sync yourself.
  • After you edit harnesspm.json, run npx harnesspm sync.
  • An install without dev dependencies, such as npm ci --omit=dev in 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.

6. Check the setup

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 lines

doctor 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.

Next