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.local port 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.
    • 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 (NA for 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.
  • 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 as terminal 2 become t2; 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 agy in 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.
  • 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.

This guide is doc/INTERFACE.md in the Deffier repo.