@gethmy/harness

@gethmy/harness

Execution motor for Harmony playbook stages.

The motor runs exactly one stage per invocation, then exits. It sets up the worktree, dispatches the stage's subagent under that stage's role, places and runs a held oracle when the gate asks for one, collects the gate's evidence, and prints what it did as newline-delimited JSON.

It deliberately does not decide anything. Harmony routes and advances; gateEvaluate in @harmony/shared turns evidence into a verdict. The motor never routes, never judges, never pushes.

A driver invokes it. The drivers are @gethmy/agent (unattended) and the hmy skill (interactive).

Installation

The interactive driver runs harmony-harness in your repository, so the motor has to be reachable from a checkout that is not Harmony's. Two ways, and the first is the one to document to a user:

npm i -g @gethmy/cli          # the front door — carries this package too
                              # (ships from the cli-v* tag; until then use the line below)
hmy stage run --card ... --stage ... --workspace ... --repo ... --session ...

npm i -g @gethmy/harness      # this package alone
harmony-harness stage run ...

Installing @gethmy/agent does not put harmony-harness on your PATH: npm links only a top-level package's bins, never a dependency's.

npx -y @gethmy/harness@latest stage run ... works without installing anything and is right for a one-off. It is wrong as a steady path, because @latest does not re-resolve — the npx cache keeps serving the build it first installed. harmony-harness --version prints the resolved path as well as the version, so a frozen cache is visible rather than silent.

Installing this package on its own is also what you do when you are building your own driver.

The full chain — bind, drive, gate, advance — is exercised end to end by e2e/planted-bug.e2e.ts (bun run e2e). It spends real agent tokens against a real Harmony API and a real Claude Code login, so it runs on demand only, never in CI.

Prerequisites

• Node.js >= 20 or Bun >= 1.0
• Git
• A Harmony account with an API key
• Claude Code available to the agent SDK

Configuration

Two environment variables, and nothing else. Both are required; the motor refuses to start without either, naming the one that is missing rather than failing later with a 401.

Variable	What it is
HARMONY_API_URL	The Harmony API base URL, e.g. https://app.gethmy.com/api. The motor appends /v1 per request, so do not include it. A trailing slash is trimmed.
HARMONY_API_KEY	A Harmony API key, or an OAuth access token (one starting with hmy_at_). Sent as the X-API-Key header — the same header @gethmy/mcp uses.

export HARMONY_API_URL="https://app.gethmy.com/api"
export HARMONY_API_KEY="…"

Generate a key with the harmony_generate_api_key tool on the Harmony MCP server, or from your account settings in Harmony.

These two variables are credentials. A stage whose role is implementer is launched with both stripped from its environment — see src/runner.ts for exactly what that does and does not close.

CLI

harmony-harness stage run \
  --card <card-id> \
  --stage <stage-id> \
  --workspace <workspace-id> \
  --repo <path-to-worktree> \
  --session <agent-session-id>

Every flag is required. --stage must match the card's current_stage: the motor refuses to collect evidence for a stage the card is not on, and refuses a stage whose owner is human.

Output is one JSON object per line on stdout — motor events, then a result object. Diagnostics go to stderr. A driver parses stdout; a human reads the driver's rendering of it.