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

Use a harness

In short

  • Ask your agent to set up harnesspm, or run two commands yourself. Your agent then gets the harness of your dependencies.
  • Review and commit what it wrote. After that, every install keeps it current.
  • Two things stay with you: which packages may run tools, and turning those tools on in your own terminal.

This page is for a project that uses libraries. To ship a harness with your own library, see Share a harness. To bring your own way of working to every repository, see Bring your own harness.

1. Set it up

Ask your agent

Paste this into Claude Code or Codex, in your project:

Set up harnesspm in this project:
install @tenphi/harnesspm as a dev dependency
and run `npx harnesspm init`.

Then tell me what it wrote, which packages have
tools that wait for my trust, and what each tool does.
Do not change "trust" yourself.

Details: https://harnesspm.tenphi.me/guides/setup

Or run it yourself

npm

shell

npm i -D @tenphi/harnesspm
npx harnesspm init

pnpm

shell

pnpm add -D @tenphi/harnesspm
pnpm exec harnesspm init

yarn

shell

yarn add -D @tenphi/harnesspm
yarn harnesspm init

Either way, init does the same:

  • It writes the rules of your dependencies into a block in AGENTS.md, and links their skills and docs.
  • It makes every install run harnesspm sync, which keeps all of this current.
  • It gives your agent three skills for harnesspm itself, so you can ask for the rest.

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.

2. Review and commit

The block in AGENTS.md is instructions to your agent. Read it once, like code.

git add AGENTS.md CLAUDE.md harnesspm.json harnesspm.lock.json package.json package-lock.json
git commit -m "chore: set up harnesspm"

With pnpm or Yarn, add their lockfile instead of package-lock.json. Everything else that harnesspm wrote stays on your machine, out of git. Set up a project lists every file.

3. Decide what may run

Rules, docs and skills work at once. Scripts, hooks and MCP servers are code, so a package’s tools stay off until you trust the package.

  1. Ask what is waiting: “Which harnesspm tools are pending, and what does each one do?”
  2. Say which packages you trust: “Trust @acme/ui in harnesspm.” Your agent adds the package to trust in harnesspm.json.
  3. Turn the tools on in your own terminal:
npx harnesspm approve

Your agent cannot do step 3. harnesspm never lets an agent give itself permissions. Trust and safety says what trust covers, and when to use "pin".

4. Keep it current

  • A full install, such as npm install, npm ci or pnpm install, runs harnesspm sync for you.
  • After npm install <pkg> or pnpm add <pkg>, no script runs. harnesspm’s own rule tells your agent to run npx harnesspm sync. When you install by hand, run it yourself.
  • A check in CI catches a missed sync. Ask for it: “Add npx harnesspm sync --check to our CI, after the install.”
  • A deploy that installs without dev dependencies, such as npm ci --omit=dev in a Docker build, skips the sync and goes on.

Upgrades then show up in pull requests, as changes to the block in AGENTS.md and to the lock.

Why one step

A package cannot set this up by itself, and that is on purpose.

  • npm 12, pnpm and Bun do not run the install scripts of dependencies until you allow each one (sources).
  • What your agent reads is your project’s decision. You take the step once, and you see every later change in review.

Next