---
language: "en"
title: "Use a harness"
canonical: "https://harnesspm.tenphi.me/getting-started/"
source: "docs/guide/getting-started.mdx"
version: "0.5.1"
index: true
---

# 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](/share/). To bring your own way of working to every repository, see [Bring your own harness](/bring-your-own/).

## 1. Set it up

### Ask your agent

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

```text
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

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](/ask-your-agent/).

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.

```shell
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](/guides/setup/#3-commit-what-it-wrote) 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:

```shell
npx harnesspm approve
```

Your agent cannot do step 3. harnesspm never lets an agent give itself permissions. [Trust and safety](/guides/trust/) 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](https://github.com/tenphi/harnesspm/blob/main/docs/research/package-managers.md#install-scripts-of-dependencies)).
* What your agent reads is your project's decision. You take the step once, and you see every later change in review.

## Next

* [Share a harness](/share/): another way to start, for a library's author.
* [Bring your own harness](/bring-your-own/): your own rules, notes and skills, in every repository.
* [Ask your agent](/ask-your-agent/): prompts for the common tasks, and what stays with you.
* [For AI agents](/agents/): every step in detail. Read it when you want to know exactly what happens.
