Profiles

Machine-wide layers applied to home harness paths, not repository working trees.

A profile is a layer tagged profile that defines your machine-wide agent harness setup. Profiles apply to home harness paths (~/.claude/, ~/.codex/, ~/.cursor/, …) — not to repository working trees. Use layer apply for project-scoped baselines.

Machine-wide home harness state

When you run ht init, HarnessTap:

Creates the local workspace at ~/.harnesstap
Seeds a default profile layer (tagged profile)
Writes ~/.harnesstap/active-profile.json pointing at that layer

init sets the active profile pointer only — it does not run global apply. Materialize home harness files after bootstrap:

ht init --main codex --aliases claude-code,cursor
ht profile use default
# or shorthand when <name> is not a reserved command:
ht default

Operational state (resources, layers, profiles, environments) lives in ~/.harnesstap/harnesstap.db. Home environment fragments may live under ~/.harnesstap/environments/.

Profile commands

ht profile list
ht profile status
ht profile create work --description "Work machine stack"
ht profile use work --harness claude-code,cursor
ht profile use work --dry-run
ht profile delete old-profile

profile use merges the profile layer and transitive layer refs, resolves the environment cascade, then writes global harness files.

Command	Scope
`profile use`	Machine home harness paths
`layer apply --project .`	Repository working tree

Root shorthand ht <name> works when <name> is a profile layer and not a reserved command (e.g. ht work ≡ ht profile use work).

Building a profile stack

Profiles are layers. Compose them like any other layer before switching:

ht layer create work --description "Work context"
ht layer edit work --add engineering-foundation --type layer
ht layer edit work --add internal-style-guide --type skill
ht profile create work    # promotes existing layer when name already exists
ht profile use work

Combine multiple context layers with layer edit --add layer:… refs. profile use expands nested layer dependencies depth-first.

Init defaults

Control bootstrap behavior with init flags:

ht init --main claude-code --aliases cursor,codex
ht init --no-default-profile    # skip default profile layer and active-profile.json
ht init --interactive           # prompt for harness selection

After init, manage harness preferences independently:

ht harness status --format json
ht harness set --main claude-code --aliases cursor,codex

The main harness is the primary write target during profile apply. Aliases receive mirrored output when you run mirror in a repo, or when profile apply includes multiple harnesses via --harness.

Cloud-backed profiles

Search, pull, and publish profile-tagged layers through HarnessTap Cloud:

ht auth login
ht profile list --search react --remote-only
ht profile pull org/work-stack
ht profile publish work --org acme --catalog default

profile pull is an alias for layer pull with a warning when the remote layer is not profile-tagged. profile publish targets org catalogs for teammate discovery.

When to use profiles vs projects

Situation	Use
Separate work / personal / client setups on one machine	Profiles (`profile use`, `ht <name>`)
Repo-specific team baseline	`layer apply --project .`
Sync alias harness files from on-disk main without re-applying a layer	`mirror`
Detect manual edits after apply	`status --check`

Profiles answer "what runs on this machine by default?" Projects answer "what does this repository get?"

Layers — composition, plugin pins, catalog baselines
Projects — repo-scoped apply and mirror
Getting started — init and first apply
Cloud connection — authenticate and publish
Command reference — profile command group
Scenario 36 — switch global profile presets