How to use Shepi.

First launch

1. Install Herdr. It is free and runs your agents:

   curl -fsSL https://herdr.dev/install.sh | sh

2. Download Shepi, drag it to Applications and open it. It finds Herdr, starts Herdr's server if it isn't running, and shows every space and agent you already have.
3. Haven't installed Herdr yet? Shepi says so and gives you the command; once Herdr is there, Shepi connects by itself. If your Herdr is too old, it shows how to update it.

Your 14 days start the first time Shepi connects to Herdr. Every feature works, with no account and no card.

The prefix

Everything you type goes into the pane you're in. To talk to Shepi instead, press the prefix, then one key: ⌃B v splits the pane to the right.

• Forgot the key? Press the prefix and wait half a second: a strip shows the keys that make sense right now.
• Don't know it at all? ? opens every action with its key; type what you want and press Return.
• Rather click? Almost every key has a mouse equivalent, and every control's tooltip names its keys.

The keys are Herdr's, read live from its config. Change them there and Shepi follows; Shepi never edits that file.

Sidebar, tabs, panes and spaces

Sidebar

Spaces first, each with how many agents are working, need you, are done or idle; then your agents, each with its state and its product's mark. ⇧⌘1 shows the sidebar with the keyboard in it (arrows move, Return goes there) and hides it again. Drag its edge to make it wider.

Panes

Tabs

Spaces

Closing something whose agent is still working or waiting for you asks first, right over it: ⌘W closes, esc keeps. Idle agents and plain shells close at once.

When an agent needs you

When an agent stops to ask (before it deploys, deletes or installs), it turns amber in the sidebar, its pane header and the status line, and you hear Herdr's own sound. A card shows what it wants to run when the agent says so; a banner reaches you even with the sidebar hidden. a takes you to the next agent that needs you; Review on the card does the same.

macOS notifications follow Settings › Notifications › Notify me: When away (the default), Always or Never. Amber always means one thing in Shepi: something needs you.

Find

⌘F (or /) searches agents, spaces, panes, machines and the recent output of every pane, on every machine. Type a word or two in any order and press Return to go there.

• Case and separators don't matter; first letters work: fat finds "fix-flaky-auth-test".
• One typo is forgiven in longer words; "quotes" match an exact phrase.
• After landing on output, ⌘G and ⇧⌘G step through the matches.
• Among equally good matches, what you used last comes first.

Agents on other machines

Add a machine in the sidebar, or in Settings › Machines: enter how you reach it over SSH (you@server, or a host from ~/.ssh/config), and Herdr's own setup runs in a terminal inside Shepi, so host keys and passphrases stay in your hands. Each machine gets its own group in the sidebar. A machine that needs attention shows an amber !; open its group for the reason and a Reconnect button. Rename, turn off or remove machines in Settings › Machines; they are saved in Herdr, so its terminal UI sees them too.

Screenshots and files for any agent

Copy a screenshot (⌃⇧⌘4 puts one on the clipboard) or files in Finder, then press ⌘V in a pane, or drag files onto it. On this Mac the paths are pasted; on another machine Shepi first copies the files there over your SSH connection, so an agent like Claude Code sees an image as if it were local. Up to 32 MB at a time, no folders; Shepi deletes its copies after 7 days. What a program on a server copies reaches your Mac's clipboard too.

Selecting and copying

Drag to select; letting go copies (as in Herdr; turn it off with Herdr's copy_on_select), and ⌘C copies too. Drag past the top or bottom to scroll while you select. In programs that use the mouse themselves, like most agent CLIs, hold ⌥ while dragging to select anyway.

Git at a glance

The status line shows the Git state of the folder the focused pane is working in, on this Mac or a server: the branch, what's added, edited and deleted, and commits to push or pull. Hover it for the details.

Macros

A macro types a whole sequence into the pane you're in with one key, and waits for menus before going on: switch an agent's model and effort, restart a dev server, anything you'd type. Make them in Settings › Macros, one step per line:

# Opus, high effort
type "/model"
press enter
wait for "Select model"
press down down enter
type "/effort high"
press enter

Give a macro any key you like, after the prefix or a ⌘ shortcut, or none and run it from ?. "Only for" keeps a Claude Code macro out of other panes. Try runs it right away; esc stops a running macro. Copy for Herdr's config gives you the same macro for Herdr's terminal UI.

Settings

Quit and come back

Quit Shepi or close its window whenever you like: Herdr keeps every agent running, and on your servers they keep going even while this Mac sleeps. Open Shepi again and everything is where you left it. If the connection dropped, the status line says how many panes changed meanwhile.

Updates, buying and other Macs

• Updates: Shepi offers new versions and installs them in place; Shepi › Check for Updates… looks now.
• Buying: Buy in the app or on this website, signed in with Google, GitHub or X: $19.99 once, every future update included.
• Another Mac: download Shepi and sign in with the same account. There is no license key.
• Refunds: within 30 days, no questions; see the refund policy.

Help

In Shepi, choose Help › Send Feedback (or press ⌘? and type “feedback”): describe what happened, add a screenshot, press Send. The support page has the usual fixes and a form, or write to support@shepi.app.