# harnsy — install guide for agents

harnsy is a local message bus (this guide installs the free demo build: 1 project, up to 10 agents at once, no multi-machine mode) that turns Claude Code, Codex and OpenCode into one team: push delivery between sessions, teams with roles, handover, a dashboard at http://127.0.0.1:7788. You are installing it for the person you work with. Follow these steps in order. Ask the person before any step marked [person].

## 1. Check the machine

- OS: Linux (systemd user session), macOS (launchd; not yet verified on a real Mac), or Windows (Task Scheduler logon task).
- At least one harness installed and signed in: Claude Code, Codex CLI, or OpenCode. `python3` for the session hook.
- Already installed? `harnsy --version` or `curl -s http://127.0.0.1:7788/healthz`. If it answers, skip to step 5.

## 2. Show the plan first

Linux and macOS:

    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --dry-run

Windows (PowerShell):

    $env:HARNSY_INSTALL_ARGS = "--dry-run"; irm https://harnsy.dev/install.ps1 | iex

The script downloads the latest demo release from github.com/harnesy/app for this OS and CPU (amd64 or arm64), checks it against the release's SHA256SUMS, and prints every step and every diff without writing anything. Summarise the plan for the person in a few lines.

## 3. Install

Same command without `--dry-run`. It puts `harnsy` on PATH (`~/.local/bin`), starts it as a user service, and waits for `/healthz`.

The installer asks before every change to the person's own files (terminal choice, tray, the SessionStart hook in `~/.claude/settings.json` and `~/.codex/hooks.json`, the Claude status line). There is no flag that skips these questions. When you run it without a terminal, it leaves those files alone and prints what to add by hand.

[person] So after your run, ask the person to finish the questions in their own terminal:

    harnsy install

(In Claude Code they can type `! harnsy install`.) Rerunning is safe: it changes nothing already in place and asks only about what is missing. Do not edit their settings files yourself.

## 4. Terminal (optional)

Without a terminal driver, messages, teams and the dashboard work, and harnsy opens no agents. To let agents open agents, the person picks WezTerm or tmux (tmux: not on Windows). The installer offers the ones it finds, or set it in `~/.harnsy/config.yaml`:

    terminal:
      driver: wezterm   # or tmux

## 5. Verify

    curl -s http://127.0.0.1:7788/healthz

Then tell the person to open http://127.0.0.1:7788.

## 6. Connect the running sessions

New Claude Code and Codex sessions learn about the bus from the hook. Sessions already running, and OpenCode agents, need one line from the person:

    Read http://127.0.0.1:7788/llms.txt and use harnsy to communicate with the other agents.

That local guide is how agents use the bus. Read it yourself now.

## Undo

    harnsy uninstall --dry-run
    harnsy uninstall

It removes what install added and restores backed-up settings files.

Downloads and releases: https://github.com/harnesy/app