Projects

A project is a repository (or directory tree) where HarnessTap materializes harness configuration. Commands default to the working tree (cwd / --project), not machine home.

HarnessTap walks up from that path to the nearest apm.yml.

Project files

Manifest shape

apm.yml lives at the repo root. Standard OpenAPM keys (name, version, targets, dependencies) parse. HarnessTap-only fields are first-class top-level keys: default_profile, environments, profiles, plugins. Git dependencies.apm entries (owner/repo, URL, or object-form path / ref) apply from the manifest; see Apply git dependencies. Registry strings in dependencies.mcp resolve from MCP Registry v0.1 on ht install; see MCP Registry identities.

environments is a mapping (same idea as profiles / plugins). environments.default names the active environment; other keys are named how-value bundles (values and optional secret_refs — refs only). There is no sibling singular environment / default_environment key.

name: demo
version: "1.0.0"
targets: [cursor, claude]
dependencies:
  apm:
    - team-stack
  mcp:
    - io.github.github/github-mcp-server
    - name: filesystem
      registry: false
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
default_profile: dev
environments:
  default: shared
  shared:
    values:
      REGION: us
profiles:
  - name: dev
    source: local
    selector: team-stack

Inspect the resolved file:

ht config show
ht config validate

Profiles vs projects

Switch a project-configured profile from apm.yml with ht use (--profile is a flag, not a positional name):

ht use --list
ht use --profile dev
ht use                        # interactive picker when multiple profiles exist

ht use reads the repo manifest, then applies that profile plugin the same way profile use does (machine home). To write harness files into the repository, use ht apply or ht install.