A workflow guide from the team building Shepherd. Instructions and default macOS shortcuts checked against Shepherd 0.5.6 source on September 9, 2026. Your custom bindings may differ.
With several coding agents running, the difficult part is often deciding which task needs you next. Shepherd puts agent navigation beside the workspace and keeps history available when you want to return to a previous conversation.
Start an agent where the work lives
Select the project workspace and start your installed coding-agent CLI in a terminal. Use a separate pane or tab for a second task so its conversation and output have a clear location. Confirm that each agent is working in the intended checkout.
For the managed MCP workflows in these guides, configure Codex or Claude Code under Agent management → Shepherd Skill. Installing those integrations is separate from logging in to the provider. Monitoring an agent and giving it terminal-control tools are also separate capabilities.
Find the next task to inspect
Use the agent entries in the left sidebar to navigate to an active task. The first nine entries have ⌘⌥1 through ⌘⌥9 shortcuts. Their numbers are navigation positions, not permanent IDs for a particular conversation.
An activity indicator helps you choose where to look. Check the agent’s output before deciding that it succeeded, needs an answer, or can be left alone. A reported completion is not a code review or proof that tests passed.
Use ⌘B to reopen the left sidebar if it is hidden. When the selected agent is in a crowded layout, ⌘⇧B zooms the focused pane for reading.
Revisit a conversation from Agent History
Open the right panel using Show files sidebar, then select Agent History. Choose a conversation in the relevant project context and use its resume action when you want to continue it.
Resuming a provider conversation and returning to an already-running terminal are different operations. History provides saved conversation context; it does not promise that a development server or shell from that conversation is still alive.
If resuming fails, inspect Agent management → Resume Agent. This section configures and validates the command Shepherd uses to reopen a previous Codex or Claude Code session. The provider executable must be available on the selected machine, and its authentication must still work. Avoid adding a second resume argument by hand when configuring the base command; Shepherd supplies the selected session when launching it.
Separate terminal and agent alerts
In Settings → Alarms, Task Done controls terminal-task or shell-exit notifications, while Agent Done controls agent completion or exit notifications. Set them independently according to the work you want to be interrupted for.
A terminal notification can identify an observed command or exit code. An agent notification can use its Agent History title when available. macOS notification permissions and system presentation settings affect whether a banner appears; these controls are not a guarantee that every event produces a visible banner.
Agent workflow shortcuts
The shortcuts below are the macOS defaults: ⌘ Command, ⇧ Shift, ⌥ Option, and ⌃ Control. Open Settings with ⌘, and choose Shortcuts to inspect app bindings. To customize one, click its field, press the new combination, and save the settings. ⌘⇧/ opens shortcut help. Browser comment-editor shortcuts are contextual controls rather than configurable app commands.
| Action | Default shortcut or control |
|---|---|
| Jump to agent entry 1–9 | ⌘⌥1–9 |
| Open the workspace picker | ⌘S |
| Toggle the agent sidebar | ⌘B |
| Zoom the focused agent pane | ⌘⇧B |
| Start another terminal tab | ⌘T |
| Split right / down | ⌘D / ⌘⇧D |
| Open Settings | ⌘, |
| Open shortcut help | ⌘⇧/ |
| Open Agent management | Left-sidebar button; no dedicated default app shortcut |
| Open Agent History or resume a conversation | Right-panel Agent History tab and its actions; no dedicated default app shortcut |
| Configure completion alerts | Settings controls; no dedicated default app shortcut |
Finish with evidence
When an agent reports that it is done, inspect the changed files and the checks it ran. Ask for sheperd-change-review to collect edited files in a focused review, or use browser review for visible application changes.
The purpose of monitoring is to reduce the cost of finding the right task. The decision to accept the work still belongs to you. Read how Shepherd monitors coding agents for the product principles behind that separation.
Your next workspace
Put it to work.
Try Shepherd on an Apple silicon Mac. The iOS app is currently listed as coming soon.
Get Shepherd for Mac