Glossary - solutionscay/skiff GitHub Wiki

Names match the code (apps/desktop/src), so a term here should always be grep-able. Read this before changing anything that touches the sidebar, the session tree, or keyboard navigation.

• Side panel / sidebar / tree (#sidebar-scroll, workspace/sidebar.ts, workspace/tree.ts) — the panel on the left. It is one tree, top to bottom: the Skiff agent row, the Projects head with the projects in no fleet, then one head for each fleet with its projects, then Other. Each project shows its worktrees, groups, sessions, and the Changes and Files sections under its row. "The tree", "the sidebar" and "the session list" mean this same panel.
• Terminal area / canvas (host, the layout tree in layout.ts) — everything to the right of the side panel: one pane, or several arranged in a split.

• Skiff agent row (.skiff-agent-row, app/skiffAgent.ts) — one fixed row above the Projects head, shown while the Skiff agent has a folder. Its session is left out of the tree below. With no session, a click or Enter starts one. See Skiff agent.
• Section head (.tree-head, treeSections()) — a labeled divider in the tree. Projects comes first and holds the projects in no fleet; its + adds a project. Each fleet has a head after it. Other comes last.
• Fleet (fleet in projects.toml, .fleet-head, .fleet-pick, data-key="fleet:<name>") — a named set of projects with one head in the tree and one lane in Mission control. Set it with Fleet… in the project menu, or drag a project onto another project or onto a fleet head. A click on the fleet head folds or opens the fleet, and so do Enter and Space; Right opens, Left folds. The head's + (on hover) adds a project to the fleet. Its right-click menu has Rename fleet… and Remove fleet; Remove fleet keeps the projects and takes them out of the fleet. Drag the head to move the whole fleet before or after another fleet.
• Project row (.project-pick, data-key="project:<name>") — a 40px row: a chevron, the project badge, the name, and a ⋯ (project menu) on hover or on the current row. A project with a bare worktree also gets a + there, which opens the session launch menu. The badge is the project's icon, or its initials when it has none: the first three letters of its name, or short in projects.toml, set with Initials… in the project menu. A click opens or folds the project; its sessions open from their own rows. Enter or Space opens or folds it (Right opens, Left folds). Delete/Backspace asks to close or remove the project. Drag the row to reorder projects or to move a project into or out of a fleet.
• Fold / rollup (folded, skiff.tree.folded, rollup() in tree.ts) — a fleet head or a project row can fold. Every row starts open, and the folds persist. A folded row shows a rollup: how many sessions under it wait, work, or have unread output. Only a row with children has a chevron and folds; a project with nothing under it has no chevron and does not light on hover. When the session on screen is in a folded project or fleet, the tree opens them so its row shows.
• Bare worktree (bareWorktree() in tree.ts) — a project's only worktree, the main checkout on its usual branch. It has no row of its own. Its sessions, groups, Changes and Files sit straight under the project row.
• Worktree (.wt-pick, data-wt) — a row for one Git worktree, shown when the project has more than a bare worktree. Enter or Space opens or closes it (Right opens, Left closes). Its + button (.wt-plus), shown on hover or on the current row, opens the session launch menu. Ctrl+Shift+T opens the same menu. New session in the row's Ctrl+Shift+M menu does too.
• Group (.group-pick, data-group) — a saved split layout with session panes or empty slots (what the tree shows as, for example, "2 side by side"). Opening a group is what turns it into a split in the terminal area.
• Session (.session-row, data-session) — one agent/terminal instance, backed by a PTY that skiffd owns. A session keeps running even if no pane shows it.
• Changes / Files (.files-head, .file-row) — per-worktree sections listing changed files and the file tree. A change, file, folder, Changes or Files row shows its preview while it is current (see Peek). Enter goes into the preview. Space opens or closes a header or folder. Shift+Enter on a change opens the file.
• Other (the last .tree-head) — sessions whose folder is under no project worktree (for example, one the skiff command started in a stray folder). It shows only while such a session exists. It is not a project: it has no row, no menu and no settings, and Ctrl+Shift+1..9 does not count it.
• Closed project (S.closedProjects) — a project kept in projects.toml with its settings but taken out of the tree. Reopen it from File › Open closed project…, the palette, or the welcome screen when no project is open. Removing a project drops it from projects.toml. Both end its sessions and leave the folder on disk.

• Pane (.cell in layout.ts) — one rectangle in the terminal area showing one session's live terminal. A single session with nothing else open is "one pane, no split."
• Split — two or more panes arranged by a Layout tree ({type:"split", dir, a, b}). A split is the on-screen form of a group.
• Focused pane (S.focused) — which pane currently owns the keys, as app state, drawn with a frame (.cell.focused). This can be true even when DOM focus is elsewhere (e.g., resting on a tree row) — see "Row keeps the keys" below. The frame is hidden while a group row is picked (.group-picked), since typing then does not reach the pane.
• Peek / preview (.peek, terminal/peek.ts) — the overlay over the terminal area for the current change, file, folder, Changes or Files row. It shows a diff, a terminal tool, or a card with an Open button. It has no session, group or split. The current row owns it: select() in keyboard.ts starts it, and it ends when another row becomes current. Rows declare their preview in workspace/rowActs.ts. While a preview shows, panes do not take the keys and a covered session does not count as seen.
• Empty slot (slot:, layoutSlots.ts) — a place in a group layout that has no session yet. Its picker starts a session there.
• Focus mode (S.focusMode, modes.ts) — the side panel, the top bar and the status bar hide; the panes of the current view fill the window. Ctrl+Shift+Up/Down step through the view's panes. Other keys that move in the tree do nothing. Going to another view (Next waiting, the palette, Back, a project key) ends it. With one pane, focus mode is maximize, and one press of Ctrl+Shift+E or Ctrl+Shift+Enter leaves it.
• Maximize (S.maximized, modes.ts) — only the focused pane shows, with the same chrome hidden. Ctrl+Shift+Up/Down step to the next or previous pane of the view and maximize it in its place; Ctrl+Shift+Left/Right do nothing. Going to another view ends it.
• Mission control (#mission-control, workspace/missionControl.ts, missionMotion.ts) — a board over the whole window with every session's screen, read-only text from skiffd. One lane per fleet, in tree order; projects in no fleet share a lane named Projects. Each project's part of a lane takes its project theme. Ctrl+Shift+A opens it with the focused session lit. A fleet head does not open it. The lit screen (.mission-tile.lit) is the one Enter, a click or Ctrl+Shift+Enter acts on. The search cell holds Running / All: Running (the default) shows only sessions that work or wait, and the choice is stored in [appearance] mission_filter. While it is open, it holds the keys as a dialog does. See Mission control.

• Region — one of the Tab stops F6/Shift+F6 cycle through: the tree and the terminal. The + and ⋯ buttons are not stops; their actions are in the Ctrl+Shift+M menus. A keyboard-navigation concept, not a visual container — the tree is one region even though it holds fleets, projects, worktrees, groups, and sessions.
• Current row / roving item (S.roveKey, .current, currentRow()) — the one highlighted row in the tree, which also holds the list's one tab stop (roving tabindex pattern). Ctrl+Shift+Up/Down moves it through every row, fleet heads and project rows included, and opens what it lands on right away.
• Row keeps the keys — after opening a session from the tree (by click, Enter, or Ctrl+Shift+Up/Down), DOM focus stays on the tree row, not the terminal. Typed characters, plain arrows included, still reach the terminal: passToTerminal() in keyboard.ts forwards them and moves the keys there. This is deliberate, so Delete/Escape/F2 keep acting on the row.
• Highlighted target — the menu and rename keys use the current row. The menu key opens the project menu with no row. Rename uses the focused session with no row. New session uses the row's worktree, else the focused pane's worktree. End session uses a highlighted session row, else the focused session. Ctrl+Shift+W follows the row with DOM focus, so a highlight left on a session row does not pull a session out of its group.
• Menu hint keys (hintKey() in ui/menu.ts) — a menu shows each item's key on the right. While the menu is open, that key picks the item for the menu's own target. Enter always picks the lit item, so Ctrl+Shift held from the opening key does not run Maximize.
• Palette / switcher (switcher, commands.ts) — Ctrl+Shift+P: every command, session and project by name. While it is open, it holds every app key except its own.

Skiff uses Ctrl+Shift+letter (⌘+Shift on macOS) and leaves bare Ctrl to the terminal. [keys] in projects.toml overrides any action. F1 (shortcuts) shows the full live keymap, overrides included. This page names only the keys that move you around.

• Ctrl+Shift+Up/Down (session-next/session-prev): the next or previous row in the tree — fleet head, project, worktree, group, session, Changes or Files — from anywhere, opening it. A fleet head or project row takes the keys, so Enter, Space and Left/Right fold or open it. A change or file row shows its preview, and the preview takes the keys. Changes, Files and folder rows keep the keys, so Space and Left/Right open and close them; Enter goes into their preview. In focus mode or maximize, the next or previous pane of the view. In Settings, the next or previous section. Plain Up/Down/Home/End do not move rows.
• Ctrl+Shift+Left (list-project): to the current project's row in the tree. The panes stay as they are. On the Skiff agent row, the row stays current. In Settings, to the section tabs.
• Ctrl+Shift+Right (list-back): from a project row or fleet head back to the row of the session on screen. In Settings, into the section.
• Ctrl+Shift+1..9 (Command+Shift+1..9 on macOS): the project row with that number, counted down the tree. Only project rows count: the Skiff agent row, section heads and fleet heads do not, and neither does Other. A folded fleet hides its projects, so they do not count either. The project's sessions show. This is a range, not one action, so it is not in [keys] and cannot be rebound.
• Ctrl+Shift+Home (list-main): to the current project's main worktree row, from any row, a terminal or a preview. A bare worktree has no row, so the key does nothing there.
• F6 / Shift+F6 (region-next/region-prev): step between the tree and the terminal.
• Ctrl+Shift+M (project-menu): the menu of the highlighted row; with no row, the project menu. The Menu key and Shift+F10 open the same row menu.
• Ctrl+Shift+P (palette): every command, session and project by name. In Mission control, it searches the board.
• Ctrl+Shift+A (mission-control): open or close Mission control. In it, plain arrows light a screen, Enter goes to that session, and Esc closes it. Ctrl+Shift+E (focus-mode) switches Running / All. Ctrl+Shift+P (palette) searches the board. Ctrl+Shift+Enter (maximize) goes to the lit session maximized; Ctrl+Shift+Enter again comes back.
• Ctrl+Shift+Alt+Arrow (focus-left/right/up/down): move pane focus within a split. Alt keeps Ctrl+Shift+Arrow free for list moves and terminal selection, and avoids Ctrl+Alt+Arrow, which GNOME and KDE take for workspace switching — see issue #22.