Concepts

The problem

Every agent keeps its own setup

A harness is the coding agent you run, like Claude Code, Codex, Cursor or OpenCode. Each one reads its own files, in its own format.

  1. Four harnesses, four sets of files.
  2. The same skill got copied into each one.
  3. The copies drift apart, and nobody notices.

HarnessTap keeps one source and writes each harness's files for you.

Same work, four times, slightly different each time.

HarnessTap supports 44 harnesses, 12 of them native.

FigureFour harnesses with their own files. The review skill exists four times, and two copies are older.

Resources

Resources

Every file or setting HarnessTap manages becomes a resource: the smallest piece you can reuse, combine and swap.

  1. Files lift out of each harness folder.
  2. Copies of the same thing merge into one.
  3. Each piece gets a type, like instruction, skill or MCP.

Plugin pins and plugin refs pull in more resources without copying files by hand.

12 resources, from 16 files. No duplicates.

FigureTwelve typed resources: instruction, skill, rule, MCP, hook, subagent, command, env var, model config, permission, plugin pin and plugin ref.

Context and environment

Context and environment

Context is what the agent sees before it acts. Environment is how it runs.

  1. Context: instructions, skills, rules, MCP servers, hooks, subagents and commands.
  2. Environment: env vars, model config, permissions and secret refs.
  3. Switch environments and only the values change.

Secrets come from your keychain, an env var or a file. HarnessTap stores the reference, never the value.

ht environment use staging

GITHUB_TOKEN from keychain. Sources: keychain, env, file.

FigureContext resources sit inside a violet boundary. Environment shows staging values, and the token comes from the keychain.

Plugins

Plugins

A plugin is a reusable recipe: a named bundle of context, with optional environment defaults.

  1. Context and environment fold into one plugin.
  2. Versioned with semver, so you know what you applied.
  3. Plugins compose. One can pull in another.

Tag a plugin profile to make it a machine-wide preset.

v1.5.0. Adds the review skill. Was v1.4.0.

FigureThe engineering-foundation plugin at v1.5.0 refers to guardrails and pins pr-tools from a marketplace.

Library

Your Library

Your Library is the one local home for every plugin, resource and environment you manage. The CLI calls it the workspace.

  1. Plugins shelve into your Library.
  2. Discover browses marketplaces and your org's catalogs.
  3. Add one plugin without adopting a whole baseline.

Your org publishes plugins to its Catalog. Shared profiles sit in the org catalog's Profiles tab.

python-style was just added from Discover.

FigureThe Desktop Library lists three plugins. Two carry in-use marks, and python-style was just added from Discover.

Apply

Apply to every harness

One source in your Library, written to each harness in the format it expects.

  1. Global: your machine-wide setup, in your home folder.
  2. Scope: a piece that fits one harness stays there, with a reason.
  3. Project: one repo, with ht apply --project .

In Desktop, the header on the Profile page switches between Global and Project.

ht apply engineering-foundation --project .

Wrote 3, removed 0, unchanged 28.

FigureOne thread from the Library reaches Claude Code, Codex, Cursor and OpenCode. Each gets the github server in its own format.

Profiles

Profiles, safely

A profile is a plugin tagged profile. Switch your whole machine setup with one command, and keep what you changed by hand.

  1. Pick a profile: ht profile use work.
  2. Files you edited are kept, never overwritten.
  3. Every apply is a snapshot. Check drift, then revert.

Changed only the environment? ht environment use staging --reapply rewrites the values.

ht profile use work

Wrote 4, removed 2, kept 1, unchanged 25.

We only remove what we wrote.

FigureSwitching to the work profile wrote four files, removed two and kept CLAUDE.md, which you had edited.

Start

How it fits together

  • Harness

    The coding agent you run, like Claude Code or Cursor.

  • Resource

    One typed piece: a skill, an MCP server, a rule.

  • Context

    What the agent sees before it acts.

  • Environment

    How it runs. Swap dev, staging or prod.

  • Plugin

    A versioned recipe you combine and apply.

  • Library

    Your local home for all of it.

  • Profile

    A plugin tagged profile, used machine-wide.

  • Catalog

    Where your org publishes plugins.

Set it up once. Use it everywhere.

npm i -g harnesstap·Needs Node 22 or newer.