Shepherd
A native macOS review inbox for the pull request flood.
Why
Coding agents open pull requests faster than any human can keep up with — across all of your
repositories at once, and in a study of 33,596 agent-authored pull requests, 61% carried no
recorded human review at all (the numbers). Review tools
were built for a handful of pull requests a week; Shepherd is built for the flood. It herds every
pull request from every repository into one place: a fast, local-first, keyboard-driven inbox where
you triage, review and merge without opening a browser tab. It is open source, and
docs/PRIVACY.md lists everything it sends and where.
What it does
The long form — every feature, with the decisions behind it — is in
docs/FEATURES.md.
What it looks like
The inbox. One row per pull request across every repository, with its CI state, review state and
diff size on the row itself — grouped by repository, review state or author (person, bot, or named
coding agent), whichever lens you reach for. The right pane is the pull request without leaving
the list: its CI, the files worth opening first, and a summary written by the on-device model.
The review screen. A real Monaco diff — the VS Code engine — side by side or inline, with the
unchanged stretches folded away and changes highlighted down to the word. Comment, approve,
request changes and merge without opening a browser tab.
Watched repositories. The inbox is built from @me searches, which is right until a repository
matters to you without anyone naming you on it. Add it in Settings and its open pull requests
arrive too — under Watched until you are involved in one.
How it stays yours
- Local SQLite is the source of truth. GitHub is a sync target, not a backend
(ADR 0006).
- Writes go through an outbox. Approve offline; it lands when the network does, with retries and
a staleness check.
- Secrets live in the Keychain — never in
UserDefaults, never in the database.
- Anonymous telemetry, off in one click. Thirteen allow-listed events, every property an enum
or a bucket, and never a repository, a branch or a line of code — docs/PRIVACY.md
says exactly what is sent and ADR 0036 says why. The complete
list of hosts Shepherd may contact is in
CONTRIBUTING.md; adding one requires a new ADR.
- Sync is end-to-end encrypted and self-hosted. Your bucket, your passphrase, ciphertext on the
wire (ADR 0014).
- AI runs only when you ask. Off by default, on-device where possible, and the unattended
morning digest may never call an endpoint at all. ⌘K search is the other side of the same rule:
it runs on every keystroke, so it is on-device only and has no code path to a provider
(ADR 0019).
- Crash reports stay on disk. Opt-in MetricKit JSON in Application Support, no uploader in the
code path (ADR 0017).
Keyboard
| Keys | Action | | Keys | Action |
|---|
j k | Move down / up the list | | r a | Approve |
⏎ | Open the selected pull request | | r x | Request changes |
x | Tick a row for bulk triage | | r c | Comment |
g a g r g s | Group by agent / repo / review state | | m | Merge… |
⌘K | Command palette & pull-request search | | r f · ⇧⌘⏎ | Start a focus review session |
⌘R | Sync now | | d n esc | In a session: done & next · next · end |
⌘⏎ | Submit the pending review (in the conversation's comment field: post the comment) | | | |
Two-keystroke sequences forget an unfinished prefix after 1.5 s, so a stray r never swallows the
next key.
Automation & integrations
shepherd open schnaq/review#128 # …/review/128 and a github.com PR URL work too
shepherd inbox needs-my-review # mine · involved · approved-by-me · watched
shepherd inbox --filter agent:claude-code # humans · bots · agent:<id> · repo:<owner>/<name>
shepherd fleet # every agent; add an id for one agent's page
shepherd sync # sweep every repository now
shepherd settings automation # jump to a Settings tab
Every command is a URL the app parses, so anything that can open one — Raycast, Shortcuts, a
bookmark, open(1), an n8n Execute Command node — can drive Shepherd
(ADR 0013):
| URL | Effect |
|---|
shepherd://pr/<owner>/<repo>/<number> | Open that pull request's review screen |
shepherd://inbox · shepherd://inbox?filter=<token> | Inbox, optionally filtered |
shepherd://fleet · shepherd://fleet/<agent-id> | The fleet, optionally on one agent's page |
shepherd://sync | Run one sweep now |
shepherd://settings · shepherd://settings/<tab> | Open Settings, optionally on a tab |
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
