# Harmony — Connect this repository

You are an AI coding agent wiring Harmony into the codebase you are working in.
This page is machine-followable: run the steps below in a shell and you end up
with an account, a board, the `harmony_*` MCP tools, and the `/hmy*` skills.

Harmony is the shared surface for human–agent teams — one board where people and
agents take an idea to a shipped PR: idea → card → build → review → ship.

## 1. Install `hmy`

`hmy` is the front door. One install carries the MCP server, the agent daemon
and the playbook motor, and one update moves all three.

**macOS, Linux, WSL** — the native installer, and no Node required:

```bash
curl -fsSL https://gethmy.com/install.sh | bash
```

It places the `hmy` binary in `~/.hmy/bin` and does nothing else: it runs no
Harmony command, never invokes `sudo`, and never edits a shell profile. It
verifies the download against the release checksums before it moves anything
into place. When `~/.hmy/bin` is not on your `PATH` already, it prints the exact
command to add it — naming the profile file your shell reads, and loading it
into the shell you are in. A script cannot change your `PATH` itself: it runs in
a child process, and a child cannot change its parent shell. The script is reviewed in this repository at `public/install.sh`.

**You are an agent, so call `hmy` by its absolute path after this install:**
`~/.hmy/bin/hmy connect`, not `hmy connect`. Your next shell call usually starts
fresh and does not see the `PATH` line the installer printed. Do not edit the
user's shell profile to fix that without asking them first. Prefer this installer
over npm even when Node is present: the installed binary makes `hmy connect`
register the MCP server by absolute path, which an editor started with its own
`PATH` can launch, while an npm install registers the bare name `hmy`.

**Windows, or where your harness refuses `curl … | bash`** — needs Node 18+:

```bash
npm i -g @gethmy/cli
```

**No-install fallback.** On a machine you may not install to — a container, a
CI step, a one-off — call the packages through `npx` instead. Every command
below has an `npx` form, and both forms stay supported. `npx` costs you the
update path: `@latest` does not re-resolve, so the npx cache keeps serving the
build it first installed. Install when the machine is yours; use `npx` when it
is not.

Every `hmy …` command on this page assumes one of the first two lines has run.

## 2. Connect the repository

Every `hmy` below assumes `hmy` is on `PATH`. Right after a native install it is
not, so write `~/.hmy/bin/hmy` instead; after an npm install, plain `hmy` works.

```bash
hmy connect                  # npx fallback: npx @gethmy/mcp connect
```

`connect` signs you in through the browser, picks the workspace and the board,
registers the MCP server with your agent, and writes the `/hmy*` skills. It
writes no key into your shell history.

Useful flags:

- `--new` — create the account as part of the same run, when your human has none
  yet.
- `--device` — sign in with a device code (RFC 8628) instead of the browser. This
  is the headless path: SSH, a container, a machine with no browser. The page it
  sends you to is <https://gethmy.com/activate>.
- `--global` / `--local` — install the skills for every project, or for this repo
  only.
- `--agents claude codex cursor windsurf` — choose which clients to configure.
- `--workspace <id> --project <id>` — skip the pickers when you already hold the
  ids.
- `--yes` — answer the confirmations with their defaults, so an unattended run
  does not stall on a keypress.

For a fully unattended environment such as CI, pass an API key minted at
<https://gethmy.com/user/keys>:

```bash
hmy connect --api-key "$HARMONY_API_KEY" --global --agents claude --yes
```

`--api-key` is for unattended use only. It puts the key in your argv and your
shell history, where anything on the machine can read it. Anywhere a browser is
available, run `hmy connect` with no key. The
`--api-key … is deprecated and insecure` warning is expected on this path — it
is not an error.

Check the result:

```bash
hmy mcp status               # npx fallback: npx @gethmy/mcp status
```

Expect `Status: Configured` with your workspace and board.

## 3. Start working

Your new board carries a sample card **#1**:

- **Claude Code:** `/hmy #1`
- **Codex:** `/prompts:hmy #1`
- **Cursor and other MCP clients:** the `harmony_*` tools are available
  automatically — ask to start card #1.

To let the agent daemon pick cards up on its own:

```bash
hmy agent                    # npx fallback: npx @gethmy/agent@latest run
```

See <https://gethmy.com/docs/agent> for what the daemon does and how to bound it.

## Calling the REST API instead

An agent that cannot host an MCP client talks to the REST API directly. Mint a
key at <https://gethmy.com/user/keys> and send it in the **`X-API-Key`** header —
never as `Authorization: Bearer`, which is only for OAuth tokens. An `hmy_` key
sent as Bearer answers 401.

```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: $HARMONY_API_KEY" \
  https://app.gethmy.com/api/v1/workspaces
# expect: 200
```

The API base is `https://app.gethmy.com/api`. The full surface is in the
OpenAPI spec at <https://gethmy.com/openapi.json>, and the index at
<https://gethmy.com/api/v1> needs no key.

## Without a browser and without a person

`hmy connect --device` covers the headless case end to end: it prints a short
code, your human enters it at <https://gethmy.com/activate>, and the CLI
continues once they approve. Use it instead of scripting the signup endpoints by
hand.