Keyboard shortcuts
Shepherd is built to drive from the keyboard. These shortcuts are desktop-only and are suppressed while a modal or overlay is open. The plain-key shortcuts fire only when the dashboard body has focus (not while you are typing in a field); the command bar and the Alt / Option switchers work even while the terminal is focused.
Command bar
Section titled “Command bar”| Keys | Action |
|---|---|
⌘K / Ctrl+K |
Open the command bar — a quick-switcher over your sessions, repositories, and herd lenses. Fires even while an input or the terminal is focused. Type to filter, ↑ / ↓ to move, Enter to activate the highlighted row, Esc to close. |
⌘J / Ctrl+J |
Open or close the Operator Assistant. Fires even while an input or the terminal is focused, so Ctrl+J no longer types a newline in the terminal — use Shift+Enter there. |
The command bar also carries verbs beyond navigation — including Next needs you, which jumps to the next session waiting on your reply (offered whenever another session is waiting), and Decommission, which decommissions the session you have selected (offered whenever that session is on screen). Type part of a verb’s name to surface it.
On a phone there is no keyboard shortcut: pull down at the top of the herd list instead. Release once the hint reads Release to search to open the command bar, or keep pulling until it reads Release to reload to reload the page. Swipe right on the open command bar to close it.
In New Task on a phone, pull down on the panel (anywhere outside a text field) to open the repo picker.
Destructive verbs take two presses: the first Enter (or click) arms the row, which turns red and asks you to confirm; the second decommissions. The arm clears itself after three seconds, or as soon as you type or move the cursor. Decommission still opens the usual undo window, so an accidental confirm is recoverable until it expires.
Session & herd navigation
Section titled “Session & herd navigation”These fire when the dashboard body has focus — not while typing in a field.
| Keys | Action |
|---|---|
j / ↓ |
Select the next session |
k / ↑ |
Select the previous session |
1–9 |
Select the Nth session |
n |
Open New Task |
r |
Open the Repos / backlog view |
Enter |
Return keyboard focus to the terminal |
Repos dialog
Section titled “Repos dialog”Inside the Repos dialog on desktop (opened with r above), the repo name in the header opens the repo switcher.
| Keys | Action |
|---|---|
r |
Open the repo switcher (not while typing in a field) |
↓ / ↑ |
In the switcher: move from the search into the list and between repos |
Enter |
Open the first match from the search, or the focused repo |
Esc |
Close the switcher (clears the search first, if it has text) — the dialog stays open |
When no repo is open — no dashboard filter, or several repos filtered — the dialog shows a repo grid instead, with the search focused.
| Keys | Action |
|---|---|
| (typing) | Filter the repos |
↓ |
From the search, move into the grid |
← / → / ↑ / ↓ |
Move between repos in the grid; ↑ from the first row returns to the search |
Enter |
Open the first match from the search, or the focused repo |
Esc |
Clear the search if it has text, otherwise close the dialog |
Switch sessions while the terminal is focused
Section titled “Switch sessions while the terminal is focused”Except for Alt+↑ / Alt+↓, the Alt combos work even while the terminal owns the keyboard, so you can move around the herd without leaving the active session. On macOS the modifier is ⌥ Option, and matching is on the physical key (Option changes the character that would be typed).
| Keys | Action |
|---|---|
Alt+J |
Next session |
Alt+K |
Previous session |
Alt+↓ / Alt+↑ |
Next / previous session (outside the terminal only) |
Alt+] / Alt+Tab |
Next session |
Alt+[ / Alt+Shift+Tab |
Previous session |
Alt+1–Alt+9 |
Select the Nth session |
Inside the terminal, Alt+↑ and Alt+↓ go to the agent. For example, Codex uses Alt+↑ to answer a queued question. Use Alt+J / Alt+K to switch sessions from the terminal.
The Alt+Tab / Alt+Shift+Tab variants work on macOS; on Windows and Linux the OS window switcher captures Alt+Tab before the app sees it, so use Alt+] / Alt+[ there.
Terminal
Section titled “Terminal”| Keys | Action |
|---|---|
Ctrl+Shift+C |
Copy the terminal selection (plain Ctrl+C sends an interrupt to the agent) |
New Task
Section titled “New Task”Inside the New Task prompt you can switch repositories without leaving the field.
| Keys | Action |
|---|---|
Alt+[ / Alt+] |
Previous / next repository |
Alt+1–Alt+3 |
Jump to the Nth recent repository |
Alt+R |
Open the repository picker |
⌘Enter / Ctrl+Enter |
Submit the task (plain Enter inserts a newline) |