herdr-crook

The Herdr plugin for Crook — see your AI coding agents on iPhone and iPad, and answer them with one tap.

English | 日本語

[!IMPORTANT] This plugin is the Mac side of Crook for Herdr, an iPhone and iPad app. You need the app to use it. Get it on the App Store. See crook.algorist.jp for more.

What you get

• Who needs you comes first — every agent in Herdr on your Mac, ordered waiting → done → working → idle, with the same marks as Herdr (● ◐ ✓ ○).
• Answer in one tap — when an agent asks for permission, the choices appear as buttons in the app.
• The real terminal — the live, colored terminal of any pane, with an extra keys row (esc, tab, arrows, ctrl, ^C).
• Talk, type, or attach — read the conversation as chat and send the next instruction by text or voice, with photos and @files.
• Usage at a glance — context, tokens, 5‑hour and weekly limits and cost.
• No account, no SSH setup — pair with a one‑time QR code. Crook connects only to your own Mac.

Works with Claude Code, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI (with an API key), Pi and Hermes, plus any terminal pane in Herdr. Hermes notifies you only when it's waiting for approval; working and done aren't shown.

Quick start

1. Install the plugin on your Mac:

   herdr plugin install algorist-dev/herdr-crook
   

2. Restart Herdr (herdr server stop, then herdr). On the first start the plugin starts its local relay (a launchd agent, jp.algorist.crook) and adds the prefix+m shortcut.

3. Pair: in Herdr press prefix then m (usually ctrl+b, m) and scan the QR code with the Crook app. The code works once and expires after 5 minutes.

Updating

The plugin doesn't update itself. When the Crook app says the plugin on your Mac is out of date (or after a new release), run:

herdr plugin update

Then restart Herdr (herdr server stop, then herdr). When Herdr starts, the plugin moves its local relay to the new code. Restarting stops running agents, so do it at a good stopping point.

Requirements

• macOS with Herdr 0.9 or later
• Node.js 23.6 or later (TypeScript runs directly, no build step)
• The Crook app on iPhone or iPad with iOS 18 or later (App Store)

[!TIP] Recommended: Tailscale (free for personal use) on your Mac and your iPhone or iPad, signed in to the same account.

• Connects directly from anywhere — fast, even away from home
• No time or data limit
• Doesn't go through the relay server at all

Without Tailscale, Crook connects over the same Wi‑Fi at home, and through the end‑to‑end encrypted relay server when you're away — up to 120 minutes and 200 MB per Mac per day. Enough to try Crook; if you use it away from home every day, use Tailscale. (Tailscale is a separate service, not affiliated with Crook.)

How it works

flowchart LR
  subgraph mac["Your Mac"]
    herdr["herdr"] <-- "local socket" --> plugin["herdr-crook<br/>(local relay)"]
  end
  plugin <-- "1. Tailscale" --> app["Crook app<br/>iPhone / iPad"]
  plugin <-- "2. same Wi‑Fi<br/>end‑to‑end encrypted" --> app
  plugin <-- "3. end‑to‑end encrypted" --> relay[("Relay server<br/>crook-relay.algorist.jp")]
  relay <--> app

The plugin reads your agents through Herdr's local socket and runs a small relay on your Mac. The app connects to it, trying in order:

1. Tailscale — the relay listens on your Tailscale IP and only accepts devices of the same Tailscale user.
2. Same Wi‑Fi — end‑to‑end encrypted with your Mac's key, which the app gets from the QR code.
3. Relay server (crook-relay.algorist.jp, run by Algorist on Cloudflare) — forwards end‑to‑end encrypted data it cannot read. Free, limited to 120 minutes and 200 MB per Mac per day (reset at 00:00 UTC).

The Crook app is distributed on the App Store and the relay server is operated by Algorist. This repository contains the Mac plugin only.

Privacy and security

Where	What
Your paired devices only	Agent list and status, the terminal of panes you open, the conversation of agents you open, file names for @ completion, usage numbers, your Herdr theme, and (in the QR code) your Mac's Tailscale / local addresses
Relay server	Only end‑to‑end encrypted frames it cannot read, the text of background notifications (not kept; see Notifications), plus per‑Mac daily usage counters and connection counts per IP address for rate limiting. Nothing else is stored
Algorist	Nothing. No accounts, analytics, ads or tracking — in the plugin and in the app

This is the beginning of the README. Read the rest at the original. Read the full README ↗