@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). Installing this package on its own is useful only if you are building a 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.