@gethmy/cli

hmy — one front door for Harmony.

Harmony ships three binaries from three packages: the MCP server that configures your client, the agent daemon that runs cards, and the playbook motor that executes a stage. Until this package existed you had to know which package owned the command you wanted, and install two of them by hand. Now there is one install, one update, and one name in every doc.

Install

npm i -g @gethmy/cli
hmy connect

That is the whole setup. hmy connect configures this repository and your client; hmy agent starts the daemon. hmy setup still reaches connect as a deprecated alias, so a pasted command or a CI job keeps working.

On a machine you may not install to, every command has an npx form — npx @gethmy/mcp connect, npx @gethmy/agent run — and both spellings stay supported. Read "Why not npx" below for what the install buys you.

Commands

Connect
  hmy connect [...]            Configure this repository and your client

Agent
  hmy run                      Start the agent daemon
  hmy status | health | doctor | sweep | resume | gc | recover
  hmy merge --card N [--worktree PATH]
  hmy runs list|show|grep | hmy stats | hmy scan-commands [--write]

Playbook motor
  hmy stage run --card ... --stage ... --workspace ... --repo ... --session ...

Pass-through
  hmy agent <args...>          -> harmony-agent
  hmy harness <args...>        -> harmony-harness
  hmy mcp <args...>            -> harmony-mcp

  hmy --version                Every version AND the file that answered
  hmy help

The three pass-through namespaces are not a convenience — they are what keeps this front door from going stale. A subcommand added to @gethmy/agent tomorrow is reachable as hmy agent <that command> without a new hmy.

It re-implements nothing

Each subcommand resolves the owning package's real bin and hands the process over. hmy merge and harmony-agent merge are the same code with the same gates, so there is no second merge policy for anyone to forget to update. Signals are forwarded, so ctrl-c on hmy run reaches the daemon rather than orphaning it, and the child's exit code is yours.

npx is the fallback, not the steady path

npx -y @gethmy/agent@latest is right for a one-off and wrong as a steady path: @latest does not re-resolve. The npx cache serves the build it first installed, so a machine can keep running a months-old daemon and say nothing about it — measured 2026-09-09, when a restart six minutes after @gethmy/agent 1.38.0 published still ran 1.37.0 out of ~/.npm/_npx/<hash>.

For a command that decides whether a pull request merges, that is the wrong trade. Install once, update in one place:

npm i -g @gethmy/cli@latest

hmy --version prints the resolved path beside every version, which is what tells a frozen cache from an install:

@gethmy/cli 0.1.0
  /usr/local/lib/node_modules/@gethmy/cli/dist/cli.js
@gethmy/agent 1.41.1
  /usr/local/lib/node_modules/@gethmy/cli/node_modules/@gethmy/agent/dist/cli.js
...

An existing per-package install keeps working

If @gethmy/agent or @gethmy/harness is already installed globally, it keeps working beside this package; you do not need to remove it. This package does not ship harmony-agent, harmony-harness or harmony-mcp bins of its own: npm would then have two packages claiming one command name, and which build answered would depend on install order — the silent-staleness problem this package exists to end.