Concepts overview

HarnessTap keeps assistant configuration in one place while materializing platform-specific files for Claude Code, Codex, Cursor, and dozens of other agent harnesses.

Architecture

Configuration flows from sources (home defaults, existing project files, cloud plugins, public catalog baselines) into a local SQLite library, then out to target harnesses on disk.

flowchart TB
  subgraph Sources[Configuration sources]
    Home[Home defaults]
    Repo[Existing project files]
    Cloud[HarnessTap Cloud plugins]
    BuiltIn[Public catalog baselines]
  end

  subgraph Library[Local HarnessTap library]
    Resources[Canonical resources in SQLite]
    Plugins[Plugins — the what]
    Envs[Environments — the how]
    Packages[Agent Plugins packages]
  end

  subgraph Targets[Materialized harnesses]
    Claude[Claude Code]
    Codex[Codex]
    Cursor[Cursor]
    Generic[Copilot, Windsurf, Warp, OpenCode, Roo, Continue, Gemini CLI]
  end

  Home --> Resources
  Repo --> Resources
  Cloud --> Plugins
  BuiltIn --> Plugins
  Resources --> Plugins
  Envs --> Plugins
  Plugins --> Packages
  Plugins --> Claude
  Plugins --> Codex
  Plugins --> Cursor
  Plugins --> Generic

A typical session looks like this:

sequenceDiagram
  participant User
  participant CLI as ht CLI
  participant DB as Local SQLite library
  participant Project as Target project

  User->>CLI: ht scan .
  CLI->>Project: Detect supported harness files
  CLI->>DB: Import resources canonically
  User->>CLI: ht plugin create / edit
  CLI->>DB: Save reusable plugin
  User->>CLI: ht apply plugin --harness ...
  CLI->>Project: Snapshot tracked files
  CLI->>Project: Write platform-specific configuration
  User->>CLI: ht status / revert
  CLI->>Project: Compare or restore snapshots

Concept model

HarnessTap separates context-side configuration (skills, MCP, hooks, rules — what the model sees) from environment-side configuration (secrets, env vars, models — how it runs).

Concept	Role
Resource	Atomic instruction, skill, rule, MCP server, hook, agent, command, etc.
Plugin	Versioned package of what resources plus a `needs` contract
Environment	Named how values (and secret refs) — prod, staging, personal
Profile	A plugin tagged for machine-wide switching (`ht work`, `profile use`)
Workspace	Local library of plugins, resources, and environments at `~/.harnesstap`
Catalog	Org-scoped published plugins you search and pull into the workspace
Account	HarnessTap Cloud login identity (`auth login`, `--account`) — not a profile

A plugin is the versioned context package you apply to projects or profiles. Plugin pins and nested plugin refs are dependencies attached during composition.

Do not confuse plugin with profile (a tagged plugin used as a global preset), account with profile, or workspace with catalog.

Cascade (last wins): home env ◂ plugin default env. Switch the home active environment to change how-values without reloading the same plugin stack.

flowchart LR
  A[Init local toolkit state] --> B[Scan repo and home defaults]
  B --> C[Store canonical resources]
  C --> D[Plugins and environments]
  D --> E[Apply with environment cascade]

Two apply surfaces

HarnessTap materializes configuration in two places:

Surface	Scope	Primary commands
Profiles	Machine-wide home harness paths (`~/.claude/`, `~/.codex/`, …)	`profile use`, `ht <profile-name>`
Projects	Repository working tree	`apply`, `mirror`, `status --check`

Profiles answer "what stack runs on this machine by default?" Projects answer "what baseline does this repo get?" See Profiles and Projects.

Where to go next

Topic	Page
Plugins, pins, catalog	Plugins
Scan, import, canonical library	Resources
Machine-wide home harness state	Profiles
Env vars, secret refs, MCP auth limits	Environments
Repo apply, mirror, drift, snapshots	Projects
Harness matrix and resource types	Supported harnesses
Cross-harness fidelity caveats	Portability limits
Full CLI surface	Command reference

Architecture

Concept model

Two apply surfaces

Where to go next

On this page