Configuration reference
In short
harnesspm.jsonis the project’s configuration. It is committed, and every field is optional.harnesspm.local.jsonand~/.harnesspm/config.jsonare per machine. They list added harnesses and can turn telemetry off.- Run
npx harnesspm syncafter every change.
{
"$schema": "https://unpkg.com/@tenphi/harnesspm/schema/harnesspm.schema.json",
"exclude": ["acme-colors:skills/acme-colors-theme", "acme-styles:hooks/check-edit"],
"replace": { "acme-styles:rules/usage": "./harnesspm/styles-usage.md" },
"patch": { "acme-colors:rules/usage": "./harnesspm/patches/acme-colors-usage.patch.md" },
"trust": { "@acme/ui": true, "@acme/colors": "pin" },
"telemetry": { "events": "all", "send": { "file": ".harnesspm/events.jsonl" } }
}| Field | Type | Default | Meaning |
|---|---|---|---|
$schema |
string | — | The JSON schema, for editors. |
exclude |
string[] | [] |
Unit IDs or package names, such as "@acme/styles", to drop, with everything only they extend. |
replace |
object | {} |
Unit ID → path of a project file that takes its place. |
patch |
object | {} |
Rule ID → path of a patch that changes some of its sections. |
trust |
object | {} |
Package name → true (follows upgrades) or "pin" (each new version needs harnesspm approve). Lets the package’s scripts, hooks, MCP servers and allow rules run. |
telemetry |
object | off | Events and the handler that gets them. |
Paths are relative to the project root. Unknown fields give a warning. The schema ships with the package, at schema/harnesspm.schema.json.
| Field | Type | Default | Meaning |
|---|---|---|---|
events |
"all" or string[] |
"all" |
Which of run, mcp, sync, why, read, skill and session to send. |
send |
string or { "file": "<path>" } |
required | The handler. A string is a command that gets each event as JSON on stdin. file appends one JSON line per event. |
The handler is active only after a person’s sync recorded it in the lock. See Telemetry.
A project can also have its own harness/ folder. It resolves like any harness package: its extends brings packages in, and its exclude, replace and patch apply for the project and for its users. harnesspm.json applies after it, for this repository only.
Per repository, excluded from git, never committed.
{
"harnesses": ["github:alex/harness"],
"telemetry": false
}| Field | Meaning |
|---|---|
harnesses |
Harnesses added with harnesspm add --local, in order. |
telemetry |
false stops every event on this machine for this repository. |
Per machine, for every repository. Same fields:
| Field | Meaning |
|---|---|
harnesses |
Harnesses added with user scope, in order. |
telemetry |
false stops every event in every repository on this machine. |
add and remove write harnesses for you.
| File | Committed | Edit by hand |
|---|---|---|
harnesspm.lock.json |
Yes | No |
The block in AGENTS.md, between BEGIN:harnesspm and END:harnesspm |
Yes | No. Text outside the block is yours. |
@AGENTS.md in CLAUDE.md, at the root and next to each nested AGENTS.md that git tracks |
Yes | The rest of CLAUDE.md is yours. |
Everything else: .claude/, .codex/, .agents/skills/, CLAUDE.local.md, node_modules/.harnesspm/ |
No | No |
The specification’s Outputs chapter lists every file.