Keyboard and the palette
The app is meant to be driven without the pointer. Everything the
pointer can reach is in the palette, the sessions themselves are one
digit away, and if you ever can't remember a binding,
⌘⇧/ puts the whole list on screen. The
hard part was never a missing chord, it was remembering them.
Customizing shortcuts
Open Settings ▸ Keyboard shortcuts, click an app shortcut, then press its replacement. Saggar refuses collisions and keeps standard macOS commands and generated session-number bindings fixed. Menus, hints, onboarding, the command palette, and the shortcut sheet update to show the current bindings. Each binding, or the whole set, can be restored to its default.
The palette — ⌘K
An empty palette leads with the ↵ again ghost, the session you last jumped to, one key away. Behind it are the verbs that act across every session at once — close all the idle ones, tell every idle agent to continue, accept every waiting prompt, walk the triage queue, collect recent errors into the scratchpad.
Everything that opens a session is here too:
- a plain session, or any model in your agent roster;
- your own session presets, and the same again in a fresh worktree;
the project's saved commands, and its scheduled tasks on demand;
the sessions it remembers closing, reopened by name with how long ago they went.
The git chips are verbs as well — push and pull appear only when the
counters have something to move, wearing
↑3 / ↓2 as
their subtitle. The rest is the quieter chrome, all findable by name: rename
and close, open in your editor, reveal, copy path, view on GitHub,
favorite, hide, settings, arming remote control, terminal text size.
Start typing and the sessions join in, fuzzy-ranked against the verbs:
jump rows wearing their live status dot, and projects to open. Lead with
> to browse the verbs alone. The
catalog is longer than the rows it shows, on purpose — an empty
palette offers the primary set and the long tail waits for a needle,
because a list you scan should be the handful you would have reached
for.
Searching inside terminals
Three or more characters and the palette also matches what is inside your terminals — every session whose buffer or scrollback contains the text, literal and case-insensitive, joins the results as a Found in … row with its freshest matching line as the subtitle. This is the “which one printed that error” case. Name and verb matches keep the top of the list, with a few slots reserved so a page of name matches can never crowd the content hits out. Buffers are snapshotted once when the palette opens, so the search costs nothing per keystroke.
Inside one terminal
- Find — ⌘F
⌘Ksays which session said it;⌘Fsays where. A small bar floats over the terminal in front of you, searching live as you type with the match scrolled into view, ↵ and ⇧↵ stepping through, and an honest “3 of 14” beside the field. Esc hands the keyboard straight back to the shell, and the query is remembered for the next⌘F.- Jump to prompt — ⌘⇧↑ / ⌘⇧↓
Walk the terminal command by command. Every prompt records where it landed, and the jump puts the previous or next one at the top of the viewport — the head of a long build's output in one press instead of fifty wheel turns.
⌘⇧↓past the last prompt lands back on the live bottom.- Quick run — ⌘P
The
git pullyou would otherwise open a whole terminal for while an agent holds the one you're in. Type one command and it runs in a live panel floated over the corner, in the selected terminal's exact directory, worktree and all. The panel never takes focus and the selection never moves. It runs as a one-shot, so a clean finish ends with a real exit code and the panel folds itself away after a readable beat; a failure leaves a live prompt sitting in its own output, ready to click into and keep as an ordinary terminal. Fire a second before the first has folded and they stack up the edge rather than stealing each other's spot.⌘⇧Mis the persistent sibling — see the monitor dock.
Finding a listening process
⌘⇧P maps ports back to the session that
started them, including processes left behind after a session closed.
From there you can return to a live owner or explicitly release an
orphan. See Project workspace for the
ownership and safety rules.
Switching sessions
⌘1–⌘9 land
on a session by its place in the menu. Those places move — attention
gravity keeps re-sorting the menu — so hold ⌘ on its own
for a second and each session's digit is drawn on its row, and on
the panes on screen. You read the number instead of remembering it, so
it doesn't matter that the order moves. A chord is not a hold, so a second modifier, any keystroke, or
⌘-tabbing away takes the numbers straight back down, and
⌘K never flashes them.
Past nine, ⌘⇧] and
⌘⇧[ step through the whole menu, wrapping
at both ends.
Every binding
| Key | Does |
|---|---|
| ⌘1–⌘9 | Go to a session by its place in the menu (hold ⌘ to see the numbers) |
| ⌘↓ / ⌘↑ | Next / previous session (⌘⇧] / ⌘⇧[ also work) |
| ⌘↩ | Answer the session in front of you |
| ⌘⇧A | Supervise or unsupervise this agent session |
| ⌘⇧R | Run next — queue a follow-on command behind the focused session |
| ⌘J | Triage the next session that needs you |
| ⌘T | New session in the current project — the type you last picked from ＋ |
| ⌘⇧T | The same, as an unassigned session with no project |
| ⌥⌘T | Open new session options |
| ⌘N / ⌘⇧N | The plain pair — just a shell, in the project or outside one |
| ⌘K | Command palette |
| ⌘P | Quick run |
| ⌘⇧M | Monitor — a persistent, docked ⌘P |
| ⌘D | Show a second session beside the current one |
| ⌘] | Move the keyboard between split panes |
| ⌘⇧W | Collapse the split |
| ⌘I | Add an image to the focused agent session |
| ⌘F | Find in this terminal |
| ⌘⇧J | Browse this terminal's prompt history |
| ⌘⇧↑ / ⌘⇧↓ | Jump to the previous / next prompt |
| ⇧PageUp / ⇧PageDown | A page of scrollback |
| ⌥⌘↑ / ⌥⌘↓ | The top / bottom of the scrollback (⌘Home / ⌘End also work) |
| ⌘⇧C | Copy the last command's output |
| ⌘⇧K | Clear this terminal — screen and scrollback, since ⌘K is the palette here |
| ⌘L | Filter the project menu |
| ⌥⌘N | Create a project |
| ⌘⇧O | Add a project |
| ⌘⇧G | View the current project on GitHub |
| ⌥⇧⌘W | Worktree cleanup — prune the project's stale worktrees |
| ⌘W | Close the focused session — falls through to closing the window when nothing is selected |
| ⌥⌘W | Close this project |
| ⌥⌘1–⌥⌘9 | Choose an option on the top attention card |
| ⌘/ | Toggle the scratchpad beside the session |
| ⌃⌘S | Overlay the project menu — an edge you reach for rather than a docked rail, at any window width |
| ⌘= / ⌘- / ⌘0 | Terminal text size — the app's own size is a separate dial in Settings ▸ Appearance |
| ⌘⇧P | Ports — what's listening, and the processes that outlived their terminal |
| ⌘⇧/ | The whole list, on screen |
| ⌘, | Settings |
| ⌘Q | Hold to quit — with a warning while anything is still running |
Interactive CLI
Run saggar tui from an interactive terminal using the same installation as the running Mac app. Outside Saggar, confirm the matching code in the Mac app; inside Saggar, press a to enable control. Consent lasts until the connection closes. The dashboard uses its own terminal keys.
In Sessions, v attaches inside the TUI. Ctrl-C, Ctrl-D, and Ctrl-Z go to the program. Press Ctrl-] then q to return to the dashboard, or Ctrl-] twice to send the literal key. Unbracketed multiline paste asks for y to confirm; n, Enter, or Esc cancels. Ctrl-] then h/j/k/l pans left/down/up/right; Ctrl-] then f follows the cursor again. Panning does not resize the Mac terminal.
| Key | Action |
|---|---|
| Arrows or j/k; Home/End | Select a row; jump to the first or last row |
| Tab / Shift-Tab | Switch sections |
| /; Esc | Search; clear search and project filters |
| Enter in Sessions | Focus the selected terminal in the Mac app |
| n; x in Sessions | Rename; confirm closing an idle terminal |
| a | Connect with Mac consent; then approve the selected prompt |
| s; o; offered number | Compose and send a message; continue; choose a prompt answer |
| t; l | Create a shell; open the agent/model picker |
| Enter in Launch | Compose an optional prompt and launch the selected model |
| e; c | Explain status; toggle conversation and output |
| Page Up/Down; g/G | Scroll output; jump to the start or latest output |
| r | Refresh or reconnect |
| p in Sessions | Open Mac presentation and supervision options |
| Up/Down or Tab; Enter or Left/Right in session options | Select a setting; change it |
| Page Up/Down; r; Esc in session options | Scroll details; refresh or reconnect; return to sessions |
| N in Projects | Create a project or reopen its draft/result |
| Ctrl-S; Enter on creation review | Review details, including from a field; confirm creation |
| Esc; r; Page Up/Down in project creation | Back/hide; refresh or reconnect while editing; scroll details |
| Enter; n in Projects | Filter terminals by project; register a directory |
| x in Projects | Confirm removal: ends terminals and clears history, keeps project files |
| m; e; i; p in Projects | Rename; edit description; edit emoji; toggle favorite |
| d in Projects; Esc in Todos | Open todos; return to Projects after clearing search |
| b in Projects; Enter in Commands | Browse saved commands; run the selected command |
| n; e; x in Commands | Create; edit; confirm deleting a saved command |
| Up/Down or Tab/Shift-Tab; Enter; Left/Right in command editor | Select a field; edit text or cycle a choice; change a choice |
| Ctrl-S; Esc in command editor | Save, including from a field; cancel a field or the editor |
| Esc in Commands | Return to Projects after clearing search |
| n; e; x in Todos | Add; edit; confirm deleting a todo |
| Enter/Space; [ / ] in Todos | Advance item state; move earlier/later within its incomplete/completed group |
| v; h in Todos | Advance project status; hide/show status |
| Page Up/Down; g/G in Projects, Todos, or Commands | Scroll details; jump to the beginning/end |
| Enter in Settings | Edit a preference; guarded settings require the Mac app |
| Enter; Esc; Ctrl-U in a field | Submit; cancel; clear the draft |
| ?; q or Ctrl-C; Ctrl-Z | Toggle help; quit; suspend (resume with fg) |
| Left/Right; Home/End; Delete in a field | Move the cursor; jump to either end; delete forward |
In Projects, x removes the selected project after you type remove. Removal ends all its running terminals and clears terminal history; project files stay on disk. Page Up/Down scroll the confirmation details, and Esc cancels. Run the TUI outside that project before removing it.
In Sessions, p opens options for the selected Mac session. Use Up/Down or Tab to select Mac view or Supervision, and Enter or Left/Right to change it. Disabling supervision requires typing disable; future agent permission prompts can then receive the default answer automatically. Enabling supervision takes effect immediately. Mac view offers Automatic, Conversation, and Terminal, and shows the effective view after fallback. These settings affect the Mac session; c still switches only the TUI output view. Page Up/Down scroll details, r refreshes or reconnects, and Esc returns to sessions.
The TUI project list follows the Mac's organization: projects with open terminals come first, parent folders define groups, and favorites come first within each group, followed by alphabetical names. Arrow keys select projects and skip group headings. Phone-specific ordering and named groups stay separate. The TUI currently lists all registered projects, including those hidden from the Mac's resting Project menu.
In Projects, N opens project creation. Choose the parent folder, name, local or private/public GitHub repository, and optionally an agent/model, reasoning effort, and prompt. Up/Down or Tab selects a field; Enter edits text or cycles a choice, and Left/Right changes choices. Ctrl-S saves the current field and opens review; Enter on review starts creation. Esc returns from review to editing, or hides the form. While creation runs, you can control and attach to other terminals; N reopens its progress or retained result. Page Up/Down scroll details, and r refreshes or reconnects while editing. Partial results show the folder, registration/launch status, and warnings. After a timeout or disconnect, inspect the destination before starting again: requests are never replayed. On a result, n opens a new blank draft and Enter returns to Projects.