# Install the Collector

> The conditions, the commands, what setup changes on your Mac, the two codes of pairing, the expected output, updates and common failures.

Validated against app `ae3b0ef2` and Collector `0.9.0` (`54621da`), 11 November 2026.

The Collector (*Collecteur* in the French interface) is the program that counts, on your computer, what supervising
your coding agents asks of you, and sends those Counts to the service. Installing it is optional: profiles work
without it.

## Conditions

Check all four before you start. Homebrew refuses the install when the first one is not met.

| Condition | Detail |
|---|---|
| macOS 26 (Tahoe) or later | Apple silicon or Intel |
| Claude Code | already used on this Mac. Codex sessions are not counted by this build |
| Homebrew | the `brew` command works in your terminal |
| An invited e-mail address | the one you sign in to `https://app.humanload.eu` with |

During the closed beta, Homebrew is the only way to install. The build is not signed or notarized by Apple: Homebrew
installs the binary whose fingerprint the public formula pins. You can read the formula, `humanload.rb`, in the
repository `cmdai-hq/homebrew-tap` on github.com before you install.

## 1. Install

```sh
brew install cmdai-hq/tap/humanload
humanload version
```

Use the full name `cmdai-hq/tap/humanload`. You should see:

```text
0.9.0
```

Installing adds the `humanload` command and nothing else: no setting is changed and nothing is sent before
the next steps.

## 2. Set up

```sh
humanload setup
```

You should see:

```text
Installation ready.
Codex: collection disabled pending the human probe.
Connect now? [y/N]
```

Answer `y` to pair now (step 3), or `n` to pair later with `humanload login`. Setup then asks one more question,
"Read only local Claude files still available for a 30-day Summary? [y/N]": it offers the History review, an estimate
computed from the Claude Code transcripts still on this Mac. Answer `n` to read nothing.

### What setup changes on your Mac

- **Your Claude Code hooks**, in `~/.claude/settings.json`. One entry is added for each of six events:
  `UserPromptSubmit`, `Stop`, `PermissionRequest`, `Notification`, and `PreToolUse` and `PostToolUse` for the
  `AskUserQuestion` tool only. Each runs the Collector's hook command. Your other hooks stay.
- **Your status line**, in the same file. A status line that runs `humanload live` is added only when you have none.
  When you have one, setup keeps it and prints the fragment to add yourself.
- **A private local folder**, `~/Library/Application Support/Humanload/`, is created.
- **Two background jobs**, in `~/Library/LaunchAgents/`. `eu.humanload.send.plist` runs `humanload send` once an
  hour, at a minute fixed for this Mac. `eu.humanload.note.plist` checks every 15 minutes whether to show the Evening
  note dialog.

macOS may announce the two jobs as new background items. The hook never calls the network: it appends one line
without text to the local folder and exits.

## 3. Pair this Mac

Pairing makes this Mac a Device (*Appareil* in the French interface): a computer where a Collector runs, named by you
and revocable by you. It uses two different codes.

- **The sign-in code** arrives by e-mail, at your invited address. You type it on the sign-in page. It proves that
  the mailbox is yours.
- **The connection code** is printed by your terminal, on the line `Connection code:`. You type it on the page
  **Pair a Device**. It proves that the Mac being paired is the one in front of you.

1. Run:

   ```sh
   humanload login
   ```

   You should see a connection code, and your browser opens `https://app.humanload.eu/device`:

   ```text
   Connection code: WDJB-MJHT
   ```

2. If the browser asks you to sign in, enter your invited address, then the sign-in code you receive by e-mail.
3. On **Pair a Device**, type the connection code from your terminal. Never type a connection code that someone sent
   you: it would pair their computer to your account.
4. Name the Device, 1 to 40 characters. The name is chosen in the browser; your computer's name is never sent.
5. Choose **Approve**. You should see "Device approved. Go back to the terminal: the rest happens on its own."
6. In the terminal, you should see:

   ```text
   Device connected.
   ```

The connection code is valid for 10 minutes at most. The Device key that the service returns is stored in your
Keychain, and in no file. A first send follows, then your browser opens your week of Counts.

## 4. Check

```sh
humanload status
```

You should see lines like these. The dates are examples; `Connection: connected` and `Hook: events received` are the
two that matter.

```text
Humanload 0.9.0
Connection: connected
Last sent: 2026-11-11T10:17:03+01:00
Next allowed send: 2026-11-11T11:07:03+01:00
Pending days: 0; rejected: 0
Open days: yes
Note: local no; server no
Summary: local no; server no
Update: disabled for this build
Hook: events received
Anomalies: 0
Final lines without newline: 0
Codex: collection disabled pending the human probe.
```

`Hook: never observed; check hook approval` is normal until you send a message in Claude Code. If it stays, quit and
reopen your Claude Code sessions.

```sh
humanload doctor
```

You should see:

```text
Connection and contract compatible.
```

`doctor` checks, in order, the local settings, the Device key, the name lookup of `app.humanload.eu`, the secure
connection, the service's answer and the contract version. It changes nothing.

## What runs afterwards

- **Counting.** Each Claude Code event runs the hook, which keeps a line without text in the local folder.
- **Sending.** Once an hour at most, the Collector sends the days whose Counts changed.
  [What leaves your computer](/what-leaves-your-computer.md) lists every field.
- **The Evening note.** Between 19:00 and 23:30, after at least six messages that day and a 20-minute pause, a dialog
  asks how much energy you have left, from 1 to 5. The answer stays on this Mac unless you turn on its sync
  ([What leaves your computer](/what-leaves-your-computer.md#the-evening-note-and-its-consent)). This build has no
  setting that turns the dialog off; this command stops it until you next log in to macOS or run `humanload setup`:

  ```sh
  launchctl bootout gui/$(id -u)/eu.humanload.note
  ```

To see the last seven days counted on this Mac, without any network call:

```sh
humanload week
```

## Update

The Collector never updates itself. Homebrew does:

```sh
brew update && brew upgrade humanload
humanload version
```

You do not run setup again: the hooks and the background jobs call the `humanload` command that Homebrew keeps
pointed at the installed version.

## Common failures

| What you see | Cause | What to do |
|---|---|---|
| No sign-in code in your mailbox, or a refusal page instead of **Pair a Device** | The address is not the invited one. | Tell the person who invited you which address you used. |
| `Failed: connection unavailable.` right after `humanload login` | The service does not accept pairings at the moment. | Tell the person who invited you. |
| `Failed: connection unavailable.` after several minutes | The connection code expired before you approved it. | Run `humanload login` again. |
| "This code is unknown, expired or already used." on **Pair a Device** | The code was mistyped, or is older than 10 minutes. | Run `humanload login` again and type the new code. |
| `Remove a Device on the page opened, then connect again.` | You already have five Devices. | Revoke one on the page **My Devices**, then run `humanload login`. |
| `Connection: rejected — humanload login` in `humanload status` | The service refused the Device key: the Device was revoked, or your address is no longer invited. | Run `humanload login`. |
| `Diagnostic stopped: dns (…).` or `tls (…)` from `humanload doctor` | This Mac cannot reach `app.humanload.eu`. | Check the network, then run `humanload doctor` again. |
| `Failed: local state unavailable.` | The local folder cannot be read or locked right now. | Run the command again a little later. |

[Troubleshooting and limits](/troubleshooting.md) covers the app and the agent connection.
