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.
A screenshot in a chat gives an agent a picture. A browser review gives you a place to point at the running page, describe a change, and return that feedback to the agent working on the project. This guide explains the complete loop for a local web app.
Set up the agent connection
Open Agent management from the left sidebar, then choose Shepherd Skill. This is the integration installer; the separate Skills section browses skill resources. Check that Shepherd Service is ready, then install sheperd-browser-review for the provider you use, or choose Install all for the bundled terminal, browser, and change-review skills.
Use an installed and authenticated Codex or Claude Code CLI. Start the agent in a Shepherd terminal inside your project. A conversation started in another application does not automatically gain access to this workspace. Installing the skill alone does not supply the live session context.
MCP supplies the available actions and their workspace context. The skill supplies the workflow instructions: open a connected review, wait for your annotations, then act on the returned feedback. You can ask in ordinary language; the integration names retain the spelling sheperd.
Start the page and ask for a review
Run your project’s development command, such as npm run dev, and use the actual URL printed by the server. Keep that process running. Then ask the agent:
Open http://localhost:4318 in Shepherd using sheperd-browser-review and wait for my visual feedback.
Replace the example port with yours. The integration opens an agent-connected browser through sheperd_open_browser_review. By default it can reuse an existing review belonging to the same live agent connection; ask for a new review when you want a separate page.
Opening an ordinary browser tab is useful for browsing, but it does not by itself establish the review’s agent connection. If the review controls are missing, ask the agent to open the page through the browser-review skill.
Point to the change
Click Comment, then select the component you want to discuss. Write an observable request such as “Give this button more space above it on a narrow screen,” rather than “Make this better.” Hold ⌘ while clicking or dragging to add or remove targets from a multiple selection.
Use Capture area when the feedback concerns a region rather than a single component. Check the selected area before saving; the page may contain account information or unrelated content that should not be included in the review.
Press ⌘Enter to save a comment. Ordinary Enter inserts a new line. Esc cancels the current draft. You can collect several comments before returning to the agent.
Send, implement, and check again
Open the review comments, select Send review, inspect the confirmation, then choose Send to agent. Saving a draft and sending the collected review are separate actions. Keep the originating agent session available so the feedback has a live destination.
Ask the agent to implement the requested changes and reopen or refresh the page. Check the result at the same viewport size. A comment is a request, not evidence that the change was implemented correctly.
Browser review 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 |
|---|---|
| Save the current comment | ⌘Enter, while editing a review comment |
| Insert a comment line break | Enter |
| Cancel the current draft | Esc |
| Extend or reduce target selection | Hold ⌘ while selecting |
| Reload the focused browser | ⌘R |
| Reload without cache | ⌘⇧R |
| Find text in the focused browser | ⌘F |
| Open browser developer tools | ⌘⌥I or F12 |
| Start commenting or capture an area | Comment / Capture area buttons; no dedicated default app shortcut |
| Send the collected review | Send review, then Send to agent; no dedicated default app shortcut |
When the connection is missing
Confirm that the project server is still running and that you used its actual port. Then check the service and provider installation in Agent management → Shepherd Skill. Start a fresh agent session inside the intended Shepherd workspace after installing the integration. An agent outside Shepherd can have the skill text available while still lacking the session-scoped MCP tools.
For running the server in a separate pane, follow the terminal-control guide. For the reasoning behind keeping a review attached to its task, see why workspace context matters.
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