shepherdr.

For the work between agent and human

Keep your
agents in view.

See what runs, what needs you, and what comes next. From your Mac or iPhone.

Set up Shepherd

Your agents keep working.
You keep the context.

See the work

Spaces, agent state, goals, and quota. Read the initial instruction and referenced documents without opening a terminal.

Know where you are needed

Questions and approvals belong in the Inbox. Open the exact agent terminal when you need direct access.

Ask for a report

The Chief of staff reads agent status. Talk or type in one saved conversation.

The connection

Pair each device.
Keep one workspace.

The host runs beside herdr on your Mac. Both apps connect to that host, including the app on the same Mac.

Your iPhone does not need to run herdr. Closing the terminal view leaves the agent running.

  1. 1

    Create a pairing ticket

    Use the Shepherd plugin on your Mac. Choose status access or terminal control.

  2. 2

    Paste it into the app

    Open Pair on your iPhone or Mac app. Paste the ticket, then compare the displayed host fingerprint.

  3. 3

    Repeat for the other device

    Each ticket works once and expires after two minutes. Create a new ticket for each device.

Start on the same network.

The Mac must stay awake and the host must run. Access across networks requires a reachable host or a configured relay. Pairing alone does not configure remote access.

Three parts.
One place to start.

Shepherd is in development. Public Mac downloads and an iOS TestFlight link are not available yet. These steps describe the current preview setup.

Start where the agents run.

The plugin manages the host service and creates pairing tickets. Install it on the computer that runs herdr.

  • Use a stable Shepherd source checkout with Bun and herdr installed.
  • Run setup to install or start the host service.
  • Install reporting so agents can report tasks and progress.

Source access is required for the current preview. Do not install the service from a temporary folder.

From your Shepherd source folder

bun packages/shepherdr-host/bin/plugin.ts setup
bun packages/shepherdr-host/bin/plugin.ts install-reporting

Create a status pairing ticket

bun packages/shepherdr-host/bin/plugin.ts pair

The host writes the ticket to pairing-code.txt in its runtime folder. Treat the ticket as a temporary secret.

A few useful details.

Do I need to keep a token?

For device pairing, no long-lived token needs to be copied each time. The app keeps its device key and remembers the host after pairing. Account quota credentials are separate.

Can I type into an agent terminal?

Yes, with terminal control access. Use pair-terminal instead of pair when creating the ticket. Status pairing does not grant terminal access.

bun packages/shepherdr-host/bin/plugin.ts pair-terminal
What does the reporting installation add?

It installs the Shepherd reporting skill for Claude and Codex, plus a Claude session reminder. Agents use the reporter to record tasks, progress, and evidence. Existing agents must read the skill before they use it.

Can two people work together?

More than one device can pair with a host. Shared annotation and multiplayer review are not available yet. The Chief supports one active voice call at a time.

What happens if my Mac sleeps?

The phone cannot read fresh agent state while the host is unavailable. Keep the Mac awake for remote use. The app reconnects when the host is reachable again.

How do I remove access?

Use Forget in the app to remove its local pairing. The plugin also has a Remove all paired devices action to revoke access at the host.