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 layers, 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 layers]
    BuiltIn[Public catalog baselines]
  end

  subgraph Library[Local HarnessTap library]
    Resources[Canonical resources in SQLite]
    Plugins[Plugins — the what]
    Envs[Environments — the how]
    Layers[Configured layers]
    Bundles[Layer v1 TOML]
  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 --> Layers
  BuiltIn --> Plugins
  Resources --> Plugins
  Plugins --> Layers
  Envs --> Layers
  Layers --> Bundles
  Layers --> Claude
  Layers --> Codex
  Layers --> Cursor
  Layers --> 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 layer create / edit
  CLI->>DB: Save reusable layer
  User->>CLI: ht layer apply layer --harness ...
  CLI->>Project: Snapshot tracked files
  CLI->>Project: Write platform-specific configuration
  User->>CLI: ht status / drift / 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	Bundle of what resources plus Claude config and a `needs` contract
Environment	Named how values (and secret refs) — prod, staging, personal
Layer	One or more plugins plus an optional default environment
Workspace	Local library of layers, resources, and environments at `~/.harnesstap`

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

Cascade (last wins): home env ◂ layer default env. Switch the home active environment to change how-values without reloading the same layer 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[Configured layers]
  E --> F[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	`layer 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
Layers, plugins, pins, catalog	Layers
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

Full specification: SPEC.md in the HarnessTap repository.

Architecture

Concept model

Two apply surfaces

Where to go next

On this page