Layers

A layer is HarnessTap's versioned context package: the unit you create, diff, export, publish, and apply. Layers compose plugins, plugin pins, nested layer refs, and an optional default environment.

Layers and plugins

Create and edit layers locally:

ht layer create my-setup --description "Shared project assistant setup"
ht layer edit my-setup --add research-helper --type skill
ht layer edit my-setup --add plugin_pin:formatter@my-marketplace --version "^2.1.0"
ht layer edit team-stack --add layer:shared-baseline --version "^1.2.0"
ht layer show my-setup

layer doctor checks for duplicate resources, empty content, or invalid plugin metadata. layer diff compares layer metadata and contents against another layer or a TOML bundle. layer from-project scans a repository and turns imported resources into a new layer.

Plugin pins and version policy

Plugin pins attach to a layer like any other composition item:

ht layer edit my-setup --add plugin_pin:formatter@my-marketplace --version "^2.1.0"
ht layer edit my-setup --add plugin_pin:formatter@my-marketplace --sync   # eager sync after add
ht resource sync plugin_pin:formatter@my-marketplace
ht layer apply my-setup --project . --strict-plugin-versions

On layer apply, HarnessTap compares layer plugin pins to library resolved_version values:

• Default — warn on mismatch
• --strict-plugin-versions — fail with exit code 2
• --ignore-plugin-versions — skip validation
• --sync-plugins — refresh plugin resources before materialize

Plugin install and sync providers exist for Claude Code and Cursor. Plugin-source scan covers .claude-plugin/, .cursor-plugin/, .codex-plugin/, and .github/plugin/ layouts.

Refresh policy for marketplace metadata is configured in ~/.harnesstap/config.jsonc:

{
  "plugins": {
    "refreshMaxAgeHours": 24
  }
}

resource sync uses cached metadata unless it is stale; pass --force to refresh regardless.

Environment cascade

Environments carry how values (env vars, model config, permissions, secret refs). During apply, values resolve through a cascade — last wins:

home active environment ◂ layer default environment

Switch the home active environment to change runtime values without rebuilding the layer stack. Bind a default environment to a layer with layer edit --environment <name>.

Catalog baselines

Starter layers such as engineering-foundation and frontend-engineer live in the HarnessTap Cloud public catalog, not inside the npm package.

ht layer list --search foundation --remote-only
ht layer apply engineering-foundation

ht layer apply <name> resolves bare names against the public catalog (and any orgs or libraries you have connected). Use layer pull to cache a bundle locally for offline work.

To opt out of anonymous public catalog lookups:

// ~/.harnesstap/config.jsonc
{ "catalog": { "publicCatalog": false } }

Or export HARNESSTAP_PUBLIC_CATALOG=0.

Connect additional org catalogs explicitly:

ht auth login
ht layer catalog connect <org>/<library>
ht layer pull org/layer-name

Register publish destinations before uploading:

ht layer catalog register acme/default
ht layer publish my-setup

Offline sharing

Layers move between machines as layer v1 TOML bundles (urn:harnesstap:layer:v1):

ht migrate export ./my-setup.harnesstap.toml --layer my-setup
ht migrate import ./my-setup.harnesstap.toml
ht migrate export ./team.harnesstap.toml --layer my-setup --embed-plugins

Default export path: <name>.harnesstap.toml. Bundles include one or more [[layers]] entries, optional plugin_pins, and optional root embedded_plugins when plugin trees are inlined. dependencies is included when a layer declares versioned semver constraints.

For a full workspace handoff (layers, environments, harness preferences, config), use ht migrate export with a .tar.gz archive — see Scenario 28.

For multiplayer distribution, use layer publish / layer pull via HarnessTap Cloud. See Cloud connection.

Layer workflows at a glance

Related

• Resources — what layers are made of
• Profiles — machine-wide layer apply
• Projects — repo-scoped layer apply
• Command reference — layer command group
• Scenario 7 — preview and apply
• Scenario 25 — stack multiple layers