# Set up rousr

These instructions are for you, the agent. The person you work with asked you
to set up rousr. Work through the steps in order, tell them what you are doing
in one line per step, and stop to ask only where a step says so.

The file has four parts. The person may name one ("follow rousr.dev/setup.md,
part B"); with none named, do part A and then offer B to D in one line each.

- **Part A. This machine.** Install rousr, wire every agent tool found here,
  check it. Steps 1 to 4 below.
- **Part B. Another agent on this machine** that setup could not wire itself
  (Hermes, OpenCode, an agent in a tmux pane, a script).
- **Part C. A cloud agent** (a claude.ai project, a Claude cloud session, a
  sandbox or VM) that should send to and hear from this machine.
- **Part D. An agent that only reads on its own schedule.**

# Part A. This machine

rousr delivers messages and alerts into running agent sessions. After setup,
anything sent to this session (by the person, another agent, or a monitor
such as CI) shows up between your tool calls. You never have to check an
inbox.

## 1. Install

Check the platform first: rousr runs on macOS and Linux. On Windows, stop and
tell the person rousr does not run there yet.

```sh
curl -fsSL https://rousr.dev/install.sh | sh
```

This installs one binary at `~/.config/rousr/bin/rousr` and runs
`rousr setup`, which:

- finds every agent tool on the machine from rousr's harness list
  (`rousr integrations --here` shows it) and adds rousr's hook or extension
  to each one it can wire itself (Claude Code, Codex, Copilot CLI, Cursor,
  Antigravity, Gemini CLI, pi). It adds only rousr's own entries and backs up every file
  it changes;
- starts the rousr daemon (launchd on macOS, systemd on Linux), or restarts
  it when it already runs;
- prints "left for you": only the steps no program can do for the person,
  such as adding the rousr connector in a chat app or approving Codex's
  hooks once in `/hooks`, and which open sessions need a reload;
- ends with `rousr doctor`.

Running `rousr setup` again is safe. It changes only what is missing or out of
date, so it is also how rousr is updated. `rousr setup --dry-run` shows what it
would do and changes nothing.

Tell the person each "left for you" line in plain words, one at a time, and
wait for each before the next. If the output says `~/.local/bin` is not on
PATH, show them the `export PATH=...` line and ask whether to add it to their
shell profile. Do not edit the profile without a yes.

## 2. Check it

```sh
rousr doctor
```

Every line should read `ok` or `note`. `FAIL` lines say what to run. The
doctor checks the binary (it runs `rousr version` through the hook shim), PATH, the service, the daemon, each tool's wiring,
and sends one message through the daemon and acks it. A `note` that a tool's
hooks have not fired yet goes away once a session of that tool has run a step.

## 3. Send a test message to yourself

```sh
rousr send @<this repo's directory name> "rousr works" --priority now
```

After your next tool call it shows up in your context as a `[rousr message
...]` block. Ack it the way the block says (write `rousr-ack <id>`). Tell the
person it worked.

## 4. Tell the person what they can do now

Say this, in your own words, in three short lines:

- Any agent can reach any other with `rousr send @<name> "<text>"`.
  `--priority now` interrupts at the next tool step, `next` waits for the
  next prompt, `idle` waits until the agent is idle.
- `rousr log` shows what agents said to each other: `--full` shows whole
  messages, `--pairs` shows who talked to whom.
- Alerts from CI, Sentry, Alertmanager or any webhook can go to an agent too.
  "Alerts in five minutes" in the README shows how.

## Optional

- **Names.** If the person uses [rostr](https://getrostr.sh), rousr picks up
  its names automatically, so `rousr send @gandalf` works. Nothing to set up.
- **Phone.** Ask whether they want a phone notification when a message sits
  unread. If yes, add a `[push]` section to `~/.config/rousr/config.toml` with
  an ntfy topic URL (see the README), and tell them to subscribe to that topic
  in the ntfy app. Only titles are sent.
- **Cloud agents.** See part C.

# Part B. Another agent on this machine

1. Run `rousr install --mcp`. It prints one snippet per harness for the MCP
   inbox and writes nothing. Ask the person which agent to add, pick an
   address for it (`opencode:<name>`, `hermes:<route>`, `cursor:<name>`),
   show them the snippet with that address and the file it goes in, and add
   it only after a yes.
2. For Hermes, OpenCode, ACP agents or a tmux pane, the README's Config
   section has the `[[hermes]]`, `[[opencode]]`, `[[acp]]` or `[[tmux]]`
   entry. Add it to `~/.config/rousr/config.toml` after a yes; the daemon
   reloads the file.
3. Check the new agent without spending its model turn: `rousr ping
   <address>`. A hook, inbox or monitor answers it. If it is not answered,
   the line says when rousr last saw that agent.

# Part C. A cloud agent

Cloud agents reach this machine through the hosted relay. Ask before setting
it up; it is the one part that sends mail through a server.

1. `rousr relay setup` checks the `[relay]` section and turns on sealing, so
   mail for this Mac is sealed on arrival. If `[relay]` is missing, stop and
   point the person to "Reaching rousr from the cloud" in the README.
2. Pick one address per cloud agent, such as `cloud:<owner>/<project>`.
3. Make the join message, then hand it to the person to paste into that
   agent:
   - **A claude.ai project** adds the rousr connector. Run `rousr relay
     connect <address>` and give the person the pairing code with this line:
     "Add the rousr connector, and type this code on the page that opens:
     <code>. It works once."
   - **A cloud environment that starts empty** (Claude cloud, a sandbox) is
     enrolled once: `rousr relay enroll <address>`. Its client id, secret and
     seal key go in that environment's secrets. Show them to the person only,
     never in a chat that other people or agents read, and never in a commit.
   - **A sandbox or VM with a shell but no browser** signs in with a device
     code it shows; approve it here with `rousr relay approve-device <code>
     <address>`.
4. Ask the person to send one test message from the cloud agent to
   `@<this repo's directory name>`, and confirm it arrived.

# Part D. An agent that only reads on its own schedule

Some agents only poll: a script or a local agent on a cron that runs `rousr
inbox <address>` every hour, or a cloud agent on a cron that reads through
the relay (use its `relay:` address; this needs a relay with read receipts). Ask how often it reads, then add, after a yes:

```toml
[[schedule]]
address = "<its address>"
every = "1h"
```

Senders then see when to expect a read, and an agent sender gets one note if
the reader misses it.

# If something fails

Run `rousr doctor` and show the person the output. rousr's hook never blocks
or breaks a session; if it fails, it prints nothing and the session continues.
To remove everything, run `rousr uninstall --claude --codex --launchd --apply`
(`--systemd` on Linux).