What's new since 2.0

Since 2.0, Shepherd has moved onto your phone and across your machines. There is a native iPhone app, an assistant that knows Shepherd from the inside, and tasks that run on whichever machine fits them. Agents can now work in a browser you logged in to. And two security audits hardened the whole server.

None of 2.1–2.5 is a breaking change. Upgrading is a normal bun run update, but read the note on the new sandbox default.

Shepherd for iPhone

A native SwiftUI app, not a web view, with the same herd you see in the browser:

• Sessions: the session list with its lenses, a live terminal, attachments and clipboard paste, hold-to-talk replies and an Enter chip that sends the typed prompt.
• Answering agents: Claude’s dialogs get a key row, AskUserQuestion opens as a native sheet, and you can answer plan questions and operate plan gates.
• Steering and merging: steers (edit them in place), session actions, a confirmed PR merge, and decommission from the session menu or for all merged sessions at once.
• Epics: grouped under an epic headline with their chain, tappable and controllable.
• Notifications: push via APNs, set up under Settings → Notifications. The app-icon badge counts the sessions waiting for you.
• Several servers at once, and a lean connection that stays smooth on a bad network.

Try it: join the TestFlight beta. Then pair it by scanning a QR code: Settings → Access → Connect iPhone → Show QR code.

→ Connect the iPhone app

The Operator Assistant

A Claude session that Shepherd runs for you and grounds in its own state. Ask it in plain words why the herd stalled, why an epic won’t drain or why an agent died. It reads, explains and tells you what to do.

• It can act, within limits you set. Ask it to get something done and it starts a session. Whether it may also steer, approve plans, merge or change repo automation, you decide under Settings → Assistant.
• It knows where you are. Each message carries your current view. Replies link the sessions they name, and structured or yes/no questions come with quick replies.
• It manages the backlog: the drain queue, priorities and claims.
• One per repo, if you want: a repo assistant sees only that repo, enforced by Shepherd.

Open it: Assist in the top bar, or ⌘J / Ctrl+J from anywhere.

→ Operator Assistant

Run tasks on another machine

Connect another Shepherd as a machine, for example the one on your MacBook, and start tasks there from your usual Shepherd. The whole session runs on that machine: the worktree, the agent, builds and tests.

• Automatic choice: a task that needs Xcode goes to the Mac, any other to Linux. New sessions also avoid overloaded hosts. You can always name the machine yourself.
• One herd: sessions from other machines join your lifecycle groups, labelled with the machine they run on. Terminal, steering, diff and preview are sent to that machine.
• Notifications for mirrored machines are relayed through the coordinator, without duplicates.
• Updates: update a connected machine’s Shepherd from the update window.

→ Run tasks on another machine

Shared browser

Log in once to the app you’re building, in a real Chromium on the Shepherd host. That repo’s agents then drive the same browser and keep working as the logged-in user when they test a change. Pop the Browser View out into its own tab to watch along. Off by default, on per repo.

→ Shared browser

Epics and projects

• Timing: how long an epic has been running, and when it will land.
• Incremental landing: for epics whose children can each ship on their own, children merge straight to main. No integration branch, no landing PR.
• No silent stalls: an epic says why it doesn’t run. Red landing CI is explained, with a Fix CI failures action. You can reorder the queue and let a running epic skip the usage ceiling.
• Drafts: an epic draft is reviewed as a rendered document.
• Project bootstrap: a Bootstrap task turns a PRD into a drainable project, from scaffold and guardrails to the first backlog epic. A new project’s PRD brief can take a Markdown upload.
• Drain: urgent labels jump the queue, tickets are routed to their Target repo, and possibly orphaned claims are surfaced.

→ Hands-off epics: incremental landing

More from the CLI

• shepherd wait <session> blocks until a session needs you, for scripts and other agents.
• shepherd messages <session> reads the agent’s last messages and the question it waits on.
• shepherd git <session>, shepherd diff <session> and shepherd cat <session> <path> show a worktree’s state without SSH.
• Every session reports a derived phase that says in one field whether it needs you.
• shepherd new --after TASK-07 … holds a task until another task’s PR has landed.
• Archived sessions are findable: sessions list --all, sessions show by designation.

→ shepherd CLI reference

Security hardening

Two security audits went through Shepherd’s sandbox, egress firewall, authentication and every place the server touches agent-written files. The fixes shipped in 2.3–2.5, and the first round’s findings are published as GitHub security advisories. Highlights:

• All server-side git runs through one hardened helper, so agent-written hooks and config never run on the host.
• The sandbox shares less with the host. Merges and approvals are bound to the exact head that was checked and reviewed.
• Access tokens can be scoped to repositories.
• New repos are sandboxed by default (see Upgrading).

Upgrade: these fixes are only in current releases. Run bun run update.

→ Security

Also new

Steering and review

• Session status panel: progress verdict, CI timings and steer history.
• CI steering: agents are steered when CI finishes and rebase as soon as a PR falls behind. CI watchers are denied, so agents no longer poll.
• Reviews: hold, cancel or restart an in-flight review from the review banner.
• Up Next: grouped into label bands, with an issue preview you can start from with a steer.

Settings and usage

• Per-engine defaults: default model and effort for Claude Code and Codex.
• Decision model: a Settings section for the Jev key and the judge features.
• GitHub budget: see how much of it is Shepherd and how much everything else. Agents get a truthful rate-limit budget.
• Connectors: a per-repo switch for claude.ai connectors.

Mac app

• Sidebar, new task sheet and session cards aligned with the web and iOS, with a server picker and a right-click menu.
• The local server keeps running when the app quits, and local work pauses on battery.
• Check, show and apply local backend updates.

Everywhere else

• Phone: swipe right to go back, and full swipe to decommission.
• herdr: support up to 0.9.5. Shepherd now talks to herdr over its socket by default.
• Cleanup: archiving a session tears down its worktree’s Docker Compose stacks.

For the full list, see the changelog.

Upgrading

bun run update

• New repos are sandboxed. A repo’s Sandbox setting now defaults to Default, which is standard where the bwrap self-test passes and trusted where it doesn’t. Repos that already had sessions keep trusted. standard is interactive-only, so auto-drain holds in such a repo; switch it to autonomous or trusted if it should drain. SHEPHERD_SANDBOX_DEFAULT_PROFILE still sets the global default.
• herdr socket driver on. Set SHEPHERD_HERDR_SOCKET=0 to go back to the CLI driver.

→ Configuration