Interface and shortcuts
The window
┌ rail / sidebar ┬ tabs of the current project ··················· ⊟ ▯ 🤖 ─ □ ✕ ┐
│ projects │ │
│ └ sessions │ terminal (or two side by side) │ right panel │
│ │ │ room · files · │
│ process status │ │ changes · runs │
│ open · ⚙ │ │
└────────────────┴ status bar: project · folder · sessions ····· shortcuts · ready ┘
- Sidebar: your projects and their sessions, which are terminals, agents and worktrees.
- Drag its edge to resize it.
- The button next to the Deffier name collapses it to the compact rail. The rail's top button expands it again.
- Ctrl+B (or double-clicking the edge) hides it completely. A button at the left of the tab bar then brings it back.
- At the bottom: New Session, Open Directory and Settings.
- Rename a session: double-click it (in the sidebar or on its tab). Enter saves, Esc cancels.
- Delete a session: hover it and click the bin. You confirm first. Its terminal closes; files are not touched.
- A worktree session also removes its worktree folder with git, and keeps the branch. Git refuses while the
folder has uncommitted or untracked files; the dialog says so. (The
.env.localport file Deffier wrote there is removed first, but only if you did not change it.) - A project's main session (
ROOT) can't be deleted. Remove the project instead.
- A worktree session also removes its worktree folder with git, and keeps the branch. Git refuses while the
folder has uncommitted or untracked files; the dialog says so. (The
- Remove a project: hover it and click ×. Its sessions and terminals close and it leaves Deffier. The folder and its files stay on disk; open it again any time.
- Compact rail: drag the sidebar narrow to get it.
- Projects are two-letter badges (
NAfor notes-app) in a fixed order. Switching projects never moves them. - The current project's sessions open in place under its badge, numbered 1, 2, 3… Hover a number to see the session's name and agent.
- The ring next to each number shows the session's state, read from what its terminal actually does:
- Spinning, in the text colour: working. The terminal is printing: an agent at work, or a command running. Only "waiting for you" uses amber, in every theme.
- Amber, pulsing: waiting for you. The agent stopped on a permission question, or reported
deffier status blocked. - Green dot: done. The agent worked and then went quiet, so it's your turn. Typing into the session clears it.
- Small hollow circle: idle.
- States reset when Deffier starts: a session from last time starts idle, never on an old "working".
- On another project's badge, the same ring shows when something in that project is working or waiting.
- + starts a new session in the current project.
- The open session is shaded. The button at the top (no logo) expands the sidebar again.
- At the bottom: open a project folder, and Settings.
- Projects are two-letter badges (
- Tabs: the tab bar shows only the sessions of the current project.
- Short names: new sessions are named
t1,t2,t3… (the next free number in the project). Older default names such asterminal 2becomet2; names you chose yourself are kept. - The same state ring as the rail sits on every tab: spinning, waiting for you, done or idle.
- Logo first. Each tab shows the logo of the agent running in it right now: type
agyin a plain terminal and its tab shows the Antigravity logo; exit, and it shows the terminal icon again. The same goes for the sidebar. - Long names are shortened; hover a tab for the full name.
- Double-click a tab to rename it.
- Closing a tab keeps the session in the sidebar.
- The current project's name and folder are in the status bar at the bottom.
- Short names: new sessions are named
- Top right, from left to right:
- Split terminals shows two terminals side by side.
- Agent room opens the room, where agents and you post messages.
- Runs, the robot button, shows the Autopilot jobs and swarm runs. A dot means a run is waiting for your approval.
- Settings (⚙ at the bottom of the sidebar, or Ctrl+,). Pick a section on the left; it reopens on the last one.
Esc closes it.
- Appearance: Dark or Light, then a theme. Each theme card is a small preview drawn in that theme's colours.
- Terminal: font size and font, with a live preview in your theme. Changes apply to open terminals at once.
- Sessions: restore tabs, save scrollback, save rooms.
- Agent room: animation at 15 fps (less CPU) or 60 fps.
- Project: the current project's folder, and Open folder.
- Shortcuts: every shortcut, and the button that opens the command palette (also Ctrl+P).
- About: version, data folder (
~/.swarmherd) and where the guides are.
Starting things
| To start | Do this |
|---|---|
| A terminal | + in the tab bar, or Ctrl+T (also while typing in a terminal) |
| An agent (Claude Code, Codex, Gemini, Antigravity, Hermes) | ⌄ next to +, then pick one. Or New Session at the bottom of the sidebar: pick the project, the agent by its logo, and whether it runs in the project folder or a new worktree. The agent starts in the new tab |
| A project | Open Directory at the bottom of the sidebar, or Ctrl+O outside a terminal. The folder is added and its shell opens |
| An agent on a specific account | ⌄, then Accounts. See Account profiles |
| Tasks for a group of agents | Ctrl+Shift+A, or Swarm task in the room. See Agent swarm |
| A job that runs by itself | A job file. See Autopilot |
Keyboard shortcuts
| Keys | Action |
|---|---|
Ctrl+P (or Ctrl+K, or :) |
Command palette: type :swarm, :autopilot, a theme name, … |
| Ctrl+Shift+A | Assign a task to agents (swarm) |
| Ctrl+T | New terminal tab |
| Ctrl+O | Open a project folder |
| Ctrl+B | Show or hide the sidebar |
| Ctrl+Alt+B | Show or hide the right panel |
| Ctrl+1 / 2 / 3 / 4 / 5 | Terminal / room / files / changes / runs |
| Ctrl+, | Settings |
| Ctrl+= / Ctrl+- / Ctrl+0 | Zoom in / out / reset |
While a terminal has focus, it keeps most keys for itself, because agents such as Claude Code use Ctrl+B and Ctrl+T. Ctrl+P, Ctrl+, and Ctrl+Shift+A always reach Deffier.
Settings
- Theme: pick from the list. The Dark/Light switch next to the list keeps your last theme of each mode.
- Terminal font and size.
- Persistence: whether scrollback and room assignments are restored when Deffier starts.
Keys inside a terminal
While you type in a plain shell, Ctrl+T, Ctrl+B and Ctrl+1…5 still work as listed above. While an agent runs in the terminal they go to the agent instead (Claude Code uses Ctrl+T for its task list and Ctrl+B to background a command). Ctrl+P, Ctrl+, , Ctrl+Alt+B and Ctrl+Shift+A always reach Deffier. Ctrl+O always stays with the terminal.