@gethmy/cli

@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 setup

That is the whole setup. hmy setup configures this repository and your client; hmy run starts the daemon.

Commands

Setup
  hmy setup [...]              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.

Why not npx

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
...

Per-package installs still work

Nothing here replaces npm i -g @gethmy/agent or npm i -g @gethmy/harness. 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.