Quickstart
Install HarnessTap, apply a catalog plugin, and inspect project status. Five minutes, four commands.
You will install HarnessTap, initialize local state, apply a public catalog plugin, and check status. Five minutes, four commands. This is the consumer path — you are applying someone else's plugin, not authoring one.
If you want to publish a plugin, jump to the author ramp. If you are rolling HarnessTap out for a team, start with Cloud.
1. Install HarnessTap
npm install -g harnesstap
ht -VNo global install:
npx harnesstap@latest -Vht is shorthand for harnesstap. Requires Node.js 20+. Prefer a GUI? Download Desktop — it uses the same ~/.harnesstap library.
2. Initialize
ht init --main codex --aliases claude-code,cursorht init creates ~/.harnesstap (SQLite library plus optional config.jsonc) and scans supported home harness folders. It does not write project files yet.
3. Apply a catalog plugin
Run this in a git repository:
ht apply engineering-foundationBare names resolve against the public HarnessTap Cloud catalog. apply writes harness files and apm.lock.yaml into the project. When the repo has a git origin, it stores a snapshot first.
To search first:
ht plugin list --search foundation --remote-onlyStarter plugins such as engineering-foundation live in the public cloud catalog, not inside the npm package. To opt out of anonymous public catalog lookups, set catalog.publicCatalog: false in ~/.harnesstap/config.jsonc or export HARNESSTAP_PUBLIC_CATALOG=0.
If you cloned a repo that already has apm.yml, skip the catalog plugin and onboard from the manifest:
ht installht install is the same loop as ht apply with no plugin selector — not a second resolver. Keep ht apply engineering-foundation when you are adding a named catalog plugin.
4. Check status
ht status .What to commit
After ht apply or ht install runs, these files land in your project:
| Path | Commit? | Why |
|---|---|---|
apm.yml | Yes | Project manifest — OpenAPM keys plus HarnessTap environments, profiles, and plugins. Create with ht config init (apply does not write this file) |
apm.lock.yaml | Yes | Lockfile — written by apply or ht install; pins resolved plugin versions and integrity hashes |
Harness directories the plugin wrote (for example .cursor/, .claude/, .github/, .agents/) | Yes | Deployed agent context — teammates can use the harness files on clone |
.harnesstap/local.toml | No | Uncommitted local overrides for default_profile / default_environment |
~/.harnesstap/ | No | Local library — machine state, not the repo |
What next
Use more plugins — projects, ht config init, ht install, apply, lockfile, and drift.
Author your own — scan, compose, and publish.
Cloud for teams — auth, orgs, and immutable versions.