Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

claude/ide hotkeys (#277)

Ruben Lütke11e66140f861
diff --git a/docs/product/extend-and-automate/agentic-ide.md b/docs/product/extend-and-automate/agentic-ide.md
index 0878ac6d0a..4dcd3ebdc7 100644
--- a/docs/product/extend-and-automate/agentic-ide.md
+++ b/docs/product/extend-and-automate/agentic-ide.md
@@ -116,6 +116,32 @@ closes when the whole line is done. The dialog says so while you type.
- Close one pane, a selection, or all panes of one coding-agent type only after
reviewing the confirmation. Closing stops those processes.
+### Keyboard: the Key Menu
+
+Press **Ctrl+B** (also on a Mac), then one more key, the way tmux and herdr
+work. A bar at the bottom of the window turns on and says **PREFIX** with the
+keys you can press next; `?` shows all of them, Esc or any other key goes
+back to typing. The chord is taken before the focused pane sees it, so it
+works while you type in an agent. To send Ctrl+B itself to the agent (Claude
+Code's "run in background"), press it twice. Holding Ctrl alone for a moment
+shows a small reminder of the chord.
+
+| Keys after Ctrl+B | What happens |
+| --- | --- |
+| Agent letter, then an arrow | Open that agent beside the focused pane, in the arrow's direction. Enter puts it in the even grid instead. |
+| `C` · `X` · `O` · `K` · `L` · `G` · `A` · `U` | Claude Code · Codex · OpenCode · Kimi Code · GLM · Grok Build · Antigravity · Cursor CLI (only installed ones are listed) |
+| `V` · `-` | Split the focused pane right · below, with the same agent |
+| `+` | Open the full Add coding agent dialog |
+| Arrows / Shift+arrows | Focus the neighboring pane / swap with it |
+| `Z` · `R` · `F` · `Q` · `E` | Maximize · rename · fork · close the focused pane · even out the layout |
+| `1`–`9` · `N` · `P` | Go to workspace 1–9 · next · previous workspace |
+| `Shift+N` · `Shift+W` · `Shift+D` | New · rename · close workspace |
+| `W`, then `N` · `T` · `R` · `Q` · `G` · `O` · `P` | New workspace · new worktree workspace · rename · close · Git panel · options · connect a project folder |
+| `M` · `?` | Show or hide the voice bubble · show every key |
+
+Escape closes the menu and Backspace goes back one step. Example:
+**Ctrl+B, C, →** opens Claude Code to the right of the focused pane.
+
For voice, name the pane and action: “Tell T2 to review the failing tests” or
“What is terminal three doing?” Near matches trigger a confirmation instead of
a guess. An explicit background-mission request still goes to Jarvis-Agents.
diff --git a/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx b/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
index b216d6e138..a7a3524ecf 100644
--- a/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
@@ -127,6 +127,7 @@ import {
import { installPasteBridge } from "./terminalPaste";
import { installCopyBridge } from "./terminalCopy";
import { createKeyEventChain } from "./terminalKeyChain";
+import { PANE_INPUT_EVENT, type PaneInputDetail } from "./ideHotkeys";
import { installNewlineBridge } from "./terminalNewline";
import { cancelPaneReflow, queuePaneReflow } from "./paneReflowQueue";
import {
@@ -2504,6 +2505,19 @@ export function AgenticTerminal({
}, [onToggleMaximize, onFocus]);
const toggleMaximizeAndFocus = onToggleMaximize ? toggleMaximizeAndFocusPane : undefined;
+ // Keys the IDE's key menu sends on to this pane: Ctrl+B twice types one
+ // Ctrl+B, the way tmux passes its own prefix through (see ./ideHotkeys).
+ useEffect(() => {
+ const onInput = (event: Event) => {
+ const detail = (event as CustomEvent<PaneInputDetail>).detail;
+ if (detail?.pane !== name || (workspaceId && detail.workspaceId !== workspaceId)) return;
+ termRef.current?.input(detail.data);
+ termRef.current?.focus();
+ };
+ window.addEventListener(PANE_INPUT_EVENT, onInput);
+ return () => window.removeEventListener(PANE_INPUT_EVENT, onInput);
+ }, [name, workspaceId]);
+
/*
* Catch up the instant a drag lets go.
*
diff --git a/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.test.tsx b/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.test.tsx
new file mode 100644
index 0000000000..c55f82ebc2
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.test.tsx
@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { CTRL_HINT_DELAY_MS, IdeHotkeyMenu } from "./IdeHotkeyMenu";
+import type { IdeHotkeyAction } from "./ideHotkeys";
+
+const AGENTS = [{ name: "claude", label: "Claude Code" }, { name: "codex", label: "Codex" }];
+
+function setup(enabled = true) {
+ const actions: IdeHotkeyAction[] = [];
+ const renames: string[] = [];
+ const terminalKeys: string[] = [];
+ const passed: number[] = [];
+ const view = render(<>
+ <textarea aria-label="terminal" onKeyDown={(event) => terminalKeys.push(event.key)} />
+ <IdeHotkeyMenu enabled={enabled} agents={AGENTS} pane="T1" onAction={(action) => actions.push(action)} onRenamePane={(name) => renames.push(name)} onPassThrough={() => passed.push(1)} />
+ </>);
+ const terminal = screen.getByLabelText("terminal");
+ terminal.focus();
+ const key = (init: KeyboardEventInit & { key: string }) => act(() => { fireEvent.keyDown(document.activeElement ?? terminal, init); });
+ const leader = () => key({ key: "b", code: "KeyB", ctrlKey: true });
+ return { actions, renames, terminalKeys, passed, key, leader, view };
+}
+
+describe("IdeHotkeyMenu", () => {
+ it("Ctrl+B twice hands one Ctrl+B to the pane", () => {
+ const { leader, passed } = setup();
+ leader();
+ leader();
+ expect(passed).toEqual([1]);
+ expect(screen.queryByRole("dialog", { name: "IDE shortcuts" })).toBeNull();
+ });
+
+ it("opens on Ctrl+B without the terminal ever seeing the chord", () => {
+ const { leader, terminalKeys } = setup();
+ leader();
+ expect(screen.getByRole("dialog", { name: "IDE shortcuts" })).toBeTruthy();
+ expect(screen.getByText("Claude Code")).toBeTruthy();
+ expect(terminalKeys).toEqual([]);
+ });
+
+ it("C then → asks for a Claude Code pane to the right, and swallows both keys", () => {
+ const { leader, key, actions, terminalKeys } = setup();
+ leader();
+ key({ key: "c", code: "KeyC" });
+ expect(screen.getByText("CLAUDE CODE")).toBeTruthy();
+ key({ key: "ArrowRight", code: "ArrowRight" });
+ expect(actions).toEqual([{ kind: "spawn", agent: "claude", direction: "right" }]);
+ expect(terminalKeys).toEqual([]);
+ expect(screen.queryByRole("dialog", { name: "IDE shortcuts" })).toBeNull();
+ });
+
+ it("R asks for the new pane name and hands it over on Enter", () => {
+ const { leader, key, renames } = setup();
+ leader();
+ key({ key: "r", code: "KeyR" });
+ const field = screen.getByRole("textbox", { name: /Rename T1/ });
+ fireEvent.change(field, { target: { value: "API" } });
+ act(() => { fireEvent.submit(field.closest("form")!); });
+ expect(renames).toEqual(["API"]);
+ });
+
+ it("lets every key through while closed, and stays shut while disabled", () => {
+ const { key, terminalKeys } = setup(false);
+ key({ key: "b", code: "KeyB", ctrlKey: true });
+ key({ key: "c", code: "KeyC" });
+ expect(screen.queryByRole("dialog", { name: "IDE shortcuts" })).toBeNull();
+ expect(terminalKeys).toEqual(["b", "c"]);
+ });
+
+ describe("the Ctrl hint", () => {
+ afterEach(() => { vi.useRealTimers(); });
+
+ it("shows what B does once Ctrl is held alone, and opens the menu on click", () => {
+ vi.useFakeTimers();
+ const { key } = setup();
+ key({ key: "Control", code: "ControlLeft", ctrlKey: true });
+ act(() => { vi.advanceTimersByTime(CTRL_HINT_DELAY_MS); });
+ const hint = screen.getByRole("button", { name: /opens the IDE key menu/ });
+ act(() => { fireEvent.mouseDown(hint); });
+ expect(screen.getByRole("dialog", { name: "IDE shortcuts" })).toBeTruthy();
+ });
+
+ it("never flashes during a quick Ctrl+C, and leaves when Ctrl is let go", () => {
+ vi.useFakeTimers();
+ const { key } = setup();
+ key({ key: "Control", code: "ControlLeft", ctrlKey: true });
+ key({ key: "c", code: "KeyC", ctrlKey: true });
+ act(() => { vi.advanceTimersByTime(CTRL_HINT_DELAY_MS * 2); });
+ expect(screen.queryByRole("button", { name: /opens the IDE key menu/ })).toBeNull();
+ key({ key: "Control", code: "ControlLeft", ctrlKey: true });
+ act(() => { vi.advanceTimersByTime(CTRL_HINT_DELAY_MS); });
+ expect(screen.getByRole("button", { name: /opens the IDE key menu/ })).toBeTruthy();
+ act(() => { fireEvent.keyUp(window, { key: "Control", code: "ControlLeft" }); });
+ expect(screen.queryByRole("button", { name: /opens the IDE key menu/ })).toBeNull();
+ });
+ });
+
+ it("shows a PREFIX mode bar, and ? opens the full key list", () => {
+ const { leader, key } = setup();
+ leader();
+ expect(screen.getByText("PREFIX")).toBeTruthy();
+ key({ key: "?", code: "Minus", shiftKey: true });
+ expect(screen.getByText("All keys")).toBeTruthy();
+ key({ key: "a", code: "KeyA" });
+ expect(screen.queryByRole("dialog", { name: "IDE shortcuts" })).toBeNull();
+ });
+
+ it("Escape closes the menu", () => {
+ const { leader, key } = setup();
+ leader();
+ key({ key: "Escape", code: "Escape" });
+ expect(screen.queryByRole("dialog", { name: "IDE shortcuts" })).toBeNull();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.tsx b/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.tsx
new file mode 100644
index 0000000000..b0b09aa313
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/IdeHotkeyMenu.tsx
@@ -0,0 +1,197 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Keyboard } from "lucide-react";
+import {
+ assignAgentKeys, hotkeyHints, isLeaderChord, modeBar, resolveHotkey,
+ type HotkeyAgent, type IdeHotkeyAction, type IdeHotkeyStep,
+} from "./ideHotkeys";
+
+interface Props {
+ /** Off while a dialog owns the keyboard or the IDE is not on screen. */
+ enabled: boolean;
+ /** The coding agents a new pane can run, in the order the picker lists them. */
+ agents: readonly HotkeyAgent[];
+ /** The selected pane: the one pane commands act on, and the anchor of a split. */
+ pane: string;
+ onAction: (action: IdeHotkeyAction) => void;
+ onRenamePane: (name: string) => void;
+ /** Ctrl+B twice: type one Ctrl+B into the selected pane. */
+ onPassThrough: () => void;
+}
+
+type View = IdeHotkeyStep | { menu: "rename" };
+
+const LEADER = ["Ctrl", "B"];
+/** How long Ctrl must be held alone before the hint shows; quick Ctrl+C/V never flash it. */
+export const CTRL_HINT_DELAY_MS = 400;
+
+function Cap({ children }: { children: React.ReactNode }) {
+ return <kbd className="inline-flex min-w-[1.5rem] items-center justify-center rounded-md border border-border bg-muted px-1.5 py-0.5 font-mono text-[11px] font-medium text-foreground shadow-[inset_0_-1px_0_rgba(0,0,0,0.12)]">{children}</kbd>;
+}
+
+/**
+ * The IDE's key menu: Ctrl+B, then the keys it lists; Ctrl+B twice types a
+ * Ctrl+B into the pane. It listens on the window in the capture phase, so the chord is taken
+ * before a focused terminal can hand it to the agent running there; while the
+ * menu is open every key goes to the menu and none reaches a pane.
+ */
+export function IdeHotkeyMenu({ enabled, agents, pane, onAction, onRenamePane, onPassThrough }: Props) {
+ const [view, setView] = useState<View | null>(null);
+ const [draft, setDraft] = useState("");
+ const keyed = useMemo(() => assignAgentKeys(agents), [agents]);
+ const latest = useRef({ view, keyed, pane, onAction, onPassThrough, enabled });
+ latest.current = { view, keyed, pane, onAction, onPassThrough, enabled };
+ // The element that had the keyboard before the menu opened gets it back.
+ const returnFocus = useRef<HTMLElement | null>(null);
+ // Opens the menu from outside the key handler (the Ctrl hint chip).
+ const openRef = useRef<() => void>(() => {});
+ // Ctrl held on its own for a moment: a small chip says what B does next, so
+ // the chord can be found without knowing it (see CTRL_HINT_DELAY_MS).
+ const [ctrlHint, setCtrlHint] = useState(false);
+
+ useEffect(() => { if (!enabled) { setView(null); setCtrlHint(false); } }, [enabled]);
+
+ useEffect(() => {
+ const close = (restore: boolean) => {
+ setView(null);
+ const target = returnFocus.current;
+ returnFocus.current = null;
+ if (restore && target?.isConnected) target.focus();
+ };
+ openRef.current = () => {
+ dropHint();
+ returnFocus.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+ setView({ menu: "root" });
+ };
+ const onKeyUp = (event: KeyboardEvent) => { if (event.key === "Control") dropHint(); };
+ let hintTimer: number | undefined;
+ const dropHint = () => {
+ window.clearTimeout(hintTimer);
+ hintTimer = undefined;
+ setCtrlHint(false);
+ };
+ const onKeyDown = (event: KeyboardEvent) => {
+ const { view: current, keyed: agentKeys, enabled: on } = latest.current;
+ if (!on || event.isComposing) return;
+ if (event.key === "Control") {
+ // Auto-repeat sends keydown again and again; one timer is enough.
+ if (!current && hintTimer === undefined) hintTimer = window.setTimeout(() => setCtrlHint(true), CTRL_HINT_DELAY_MS);
+ } else {
+ dropHint();
+ }
+ if (isLeaderChord(event)) {
+ event.preventDefault();
+ event.stopPropagation();
+ if (current) {
+ close(true);
+ // Twice in a row: the agent in the pane wanted its own Ctrl+B.
+ if (current.menu === "root") latest.current.onPassThrough();
+ return;
+ }
+ returnFocus.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+ setView({ menu: "root" });
+ return;
+ }
+ if (!current) return;
+ // The rename field types like any field; only Escape leaves it.
+ if (current.menu === "rename") {
+ if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); close(true); }
+ return;
+ }
+ const outcome = resolveHotkey(current, event, agentKeys);
+ if (outcome.type === "ignore") return;
+ event.preventDefault();
+ event.stopPropagation();
+ if (outcome.type === "close") { close(true); return; }
+ if (outcome.type === "step") { setView(outcome.step); return; }
+ if (outcome.action.kind === "rename-pane") {
+ if (!latest.current.pane) { close(true); return; }
+ setDraft(latest.current.pane);
+ setView({ menu: "rename" });
+ return;
+ }
+ // Hand the keyboard back first: an action that opens a dialog or focuses
+ // another pane then moves it on from there.
+ close(true);
+ latest.current.onAction(outcome.action);
+ };
+ // A click anywhere else means the user moved on.
+ const onPointerDown = (event: PointerEvent) => {
+ if (!latest.current.view) return;
+ if (event.target instanceof Element && event.target.closest("[data-ide-hotkey-menu]")) return;
+ close(false);
+ };
+ window.addEventListener("keydown", onKeyDown, true);
+ window.addEventListener("keyup", onKeyUp, true);
+ window.addEventListener("blur", dropHint);
+ window.addEventListener("pointerdown", onPointerDown, true);
+ return () => {
+ dropHint();
+ window.removeEventListener("keydown", onKeyDown, true);
+ window.removeEventListener("keyup", onKeyUp, true);
+ window.removeEventListener("blur", dropHint);
+ window.removeEventListener("pointerdown", onPointerDown, true);
+ };
+ }, []);
+
+ if (!view) {
+ if (!ctrlHint) return null;
+ return <button type="button" data-ide-hotkey-hint onMouseDown={(event) => { event.preventDefault(); openRef.current(); }}
+ className="fixed bottom-6 left-1/2 z-[90] flex -translate-x-1/2 items-center gap-2 rounded-full border border-border bg-popover px-3 py-1.5 text-xs text-popover-foreground shadow-lg">
+ <Keyboard className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
+ <Cap>Ctrl</Cap><span className="text-muted-foreground">+</span><Cap>B</Cap>
+ <span>opens the IDE key menu</span>
+ </button>;
+ }
+
+ // Prefix, workspace and direction steps: one bar along the bottom edge, the
+ // way herdr draws its PREFIX mode — it names the mode and the keys that work
+ // now, and covers nothing but the last line of the panes.
+ if (view.menu !== "help" && view.menu !== "rename") {
+ const bar = modeBar(view, keyed);
+ return <div data-ide-hotkey-menu role="dialog" aria-label="IDE shortcuts"
+ className="pointer-events-auto fixed inset-x-0 bottom-0 z-[90] flex h-8 items-center gap-3 overflow-hidden whitespace-nowrap border-t border-border bg-popover px-2 text-xs text-popover-foreground shadow-[0_-4px_16px_rgba(0,0,0,0.18)]">
+ <span className="shrink-0 rounded-sm bg-primary px-2 py-0.5 text-[11px] font-bold tracking-wide text-primary-foreground">{bar.badge}</span>
+ {pane && view.menu !== "workspace" && <span className="shrink-0 text-muted-foreground">{pane}</span>}
+ {bar.hints.map((hint) => <span key={`${hint.keys.join("+")}-${hint.label}`} className="inline-flex shrink-0 items-center gap-1">
+ {hint.keys.map((key) => <Cap key={key}>{key}</Cap>)}<span className="text-muted-foreground">{hint.label}</span>
+ </span>)}
+ </div>;
+ }
+
+ return <div data-ide-hotkey-menu role="dialog" aria-label="IDE shortcuts"
+ className="pointer-events-auto fixed bottom-6 left-1/2 z-[90] w-[min(46rem,calc(100vw-2rem))] -translate-x-1/2 rounded-2xl border border-border bg-popover p-4 text-popover-foreground shadow-2xl">
+ <div className="mb-3 flex items-center justify-between gap-3">
+ <div className="flex items-center gap-2 text-xs text-muted-foreground">
+ <Keyboard className="h-4 w-4" aria-hidden="true" />
+ <span className="inline-flex items-center gap-1">{LEADER.map((key) => <Cap key={key}>{key}</Cap>)}</span>
+ <span className="font-medium text-foreground">{view.menu === "rename" ? `Rename ${pane}` : "All keys"}</span>
+ </div>
+ <span className="text-[11px] text-muted-foreground"><Cap>Esc</Cap> close</span>
+ </div>
+ {view.menu === "rename" ? <form className="flex items-center gap-2" onSubmit={(event) => {
+ event.preventDefault();
+ const name = draft.trim();
+ setView(null);
+ if (returnFocus.current?.isConnected) returnFocus.current.focus();
+ returnFocus.current = null;
+ if (name && name !== pane) onRenamePane(name);
+ }}>
+ <label className="flex min-w-0 flex-1 items-center gap-2 text-xs text-muted-foreground">Rename {pane}
+ <input autoFocus value={draft} maxLength={40} onChange={(event) => setDraft(event.target.value)} onFocus={(event) => event.currentTarget.select()}
+ className="h-9 min-w-0 flex-1 rounded-lg border border-input bg-background px-3 text-sm text-foreground outline-none focus:border-ring focus:ring-1 focus:ring-ring/30" />
+ </label>
+ <button type="submit" className="h-9 rounded-lg bg-primary px-3 text-sm font-medium text-primary-foreground">Save</button>
+ </form>
+ : <div className="grid gap-x-6 gap-y-3 sm:grid-cols-3">
+ {hotkeyHints({ menu: "root" }, keyed).map((group) => <section key={group.title} className="min-w-0">
+ <h3 className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">{group.title}</h3>
+ <ul className="space-y-1">
+ {group.hints.map((hint) => <li key={hint.label} className="flex items-center gap-2 text-sm">
+ <span className="inline-flex shrink-0 items-center gap-1">{hint.keys.map((key) => <Cap key={key}>{key}</Cap>)}</span>
+ <span className="truncate">{hint.label}</span>
+ </li>)}
+ </ul>
+ </section>)}
+ </div>}
+ </div>;
+}
diff --git a/jarvis/ui/web/frontend/src/components/agentic/WorkspaceTerminalGrid.tsx b/jarvis/ui/web/frontend/src/components/agentic/WorkspaceTerminalGrid.tsx
index a2a3bf2a01..801f6422db 100644
--- a/jarvis/ui/web/frontend/src/components/agentic/WorkspaceTerminalGrid.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentic/WorkspaceTerminalGrid.tsx
@@ -15,6 +15,7 @@ import { cn } from "@/lib/utils";
import { PaneResizer } from "@/components/layout/PaneResizer";
import { treeLayout, treeLeaves, type LayoutNode, type PaneSeam } from "./treeLayout";
import { useTreeSizes } from "./useTreeSizes";
+import { PANE_COMMAND_EVENT, neighborInDirection, type PaneCommandDetail } from "./ideHotkeys";
import { DOCK_LABELS, GRID_LIMIT_HINT, MAX_GRID_COLUMNS, MAX_GRID_ROWS, MAX_WORKSPACE_PANES, dockPosition, fitsWorkspace, layoutSpan, paneStyle, previewDock, workspaceLayout } from "./workspaceDocking";
const GAP = 8;
@@ -333,6 +334,44 @@ export function WorkspaceTerminalGrid({ session, onChanged, onAdd, onClose, onSe
const inFlight = sizes.liveTree.current;
if (inFlight) paintDragged(inFlight);
});
+ // The IDE's key menu (see ./ideHotkeys) acts on the selected pane of the
+ // workspace on screen. The handler is rebuilt each render so it reads the
+ // current layout; the listener itself is added once.
+ const paneCommand = useRef<(detail: PaneCommandDetail) => void>(() => {});
+ paneCommand.current = ({ pane, command }) => {
+ const index = tiles.findIndex((terminal) => terminal.name === pane);
+ const terminal = tiles[index];
+ if (!terminal) return;
+ const id = idOf(terminal);
+ const focusPane = (target: TerminalState) => {
+ onSelect(target.name);
+ const typeInto = () => paneNodes.current.get(idOf(target))?.querySelector<HTMLElement>("textarea")?.focus();
+ requestAnimationFrame(typeInto);
+ };
+ if (command.kind === "focus" || command.kind === "swap") {
+ const neighbor = neighborInDirection(layout.boxes, index, command.direction);
+ const target = neighbor === null ? undefined : tiles[neighbor];
+ if (!target) { setAnnouncement(`No pane ${command.direction === "up" ? "above" : command.direction === "down" ? "below" : `to the ${command.direction}`} of ${terminal.name}.`); return; }
+ if (command.kind === "swap") { void move(id, idOf(target)); return; }
+ setMaximized(null);
+ focusPane(target);
+ return;
+ }
+ if (command.kind === "maximize") { setMaximized((current) => current === id ? null : id); focusPane(terminal); return; }
+ if (command.kind === "fork") {
+ if (terminal.accepts_prompts !== false) setForking({ name: terminal.name, agent: terminal.agent, displayName: terminal.display_name, workspaceId: session.id });
+ return;
+ }
+ if (command.kind === "rename") void rename(terminal, command.name);
+ };
+ useEffect(() => {
+ const onCommand = (event: Event) => {
+ const detail = (event as CustomEvent<PaneCommandDetail>).detail;
+ if (detail?.workspaceId === latest.current.session.id) paneCommand.current(detail);
+ };
+ window.addEventListener(PANE_COMMAND_EVENT, onCommand);
+ return () => window.removeEventListener(PANE_COMMAND_EVENT, onCommand);
+ }, []);
const showSeams = !visibleMaximized && !drag && !saving && !disabled && !optimistic && tiles.length > 1;
const dragged = drag ? session.terminals.find((terminal) => idOf(terminal) === drag.id) : null;
@@ -359,22 +398,9 @@ export function WorkspaceTerminalGrid({ session, onChanged, onAdd, onClose, onSe
if (!event.altKey || !["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.key)) return;
event.preventDefault();
if (visibleMaximized) return;
- const box = layout.boxes[index];
- if (!box) return;
- const horizontal = event.key === "ArrowLeft" || event.key === "ArrowRight";
- const sign = event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 1;
- const center = horizontal ? box.x + box.w / 2 : box.y + box.h / 2;
- const crossCenter = horizontal ? box.y + box.h / 2 : box.x + box.w / 2;
- const candidates = tiles.map((entry, at) => ({ entry, box: layout.boxes[at] })).filter((candidate) => candidate.box && idOf(candidate.entry) !== id)
- .map((candidate) => ({ ...candidate,
- distance: ((horizontal ? candidate.box!.x + candidate.box!.w / 2 : candidate.box!.y + candidate.box!.h / 2) - center) * sign,
- crossDistance: Math.abs((horizontal ? candidate.box!.y + candidate.box!.h / 2 : candidate.box!.x + candidate.box!.w / 2) - crossCenter),
- overlap: horizontal
- ? Math.min(box.y + box.h, candidate.box!.y + candidate.box!.h) - Math.max(box.y, candidate.box!.y)
- : Math.min(box.x + box.w, candidate.box!.x + candidate.box!.w) - Math.max(box.x, candidate.box!.x),
- }))
- .filter((candidate) => candidate.distance > 0.001 && candidate.overlap > 0.001).sort((a, b) => a.distance - b.distance || a.crossDistance - b.crossDistance);
- if (candidates[0]) void move(id, idOf(candidates[0].entry));
+ const direction = ({ ArrowLeft: "left", ArrowRight: "right", ArrowUp: "up", ArrowDown: "down" } as const)[event.key as "ArrowLeft"];
+ const neighbor = neighborInDirection(layout.boxes, index, direction);
+ if (neighbor !== null && tiles[neighbor]) void move(id, idOf(tiles[neighbor]));
}}
style={paneStyle(visibleMaximized === id ? { x: 0, y: 0, w: 1, h: 1 } : layout.boxes[index]!)}
className={cn("min-h-0 min-w-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
diff --git a/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.test.ts b/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.test.ts
new file mode 100644
index 0000000000..084250078e
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import {
+ LEADER_PASSTHROUGH, RESERVED_ROOT_KEYS, assignAgentKeys, hotkeyHints, isLeaderChord, modeBar, neighborInDirection, resolveHotkey,
+ type HotkeyEventLike, type IdeHotkeyStep,
+} from "./ideHotkeys";
+
+const press = (key: string, extra: Partial<HotkeyEventLike> = {}): HotkeyEventLike => ({
+ key, code: /^[a-z]$/i.test(key) ? `Key${key.toUpperCase()}` : "", ctrlKey: false, metaKey: false, altKey: false, shiftKey: false, ...extra,
+});
+
+const AGENTS = assignAgentKeys([
+ { name: "claude", label: "Claude Code" },
+ { name: "codex", label: "Codex" },
+ { name: "opencode", label: "OpenCode" },
+ { name: "grok-build", label: "Grok Build" },
+]);
+const ROOT: IdeHotkeyStep = { menu: "root" };
+
+describe("leader chord", () => {
+ it("is Ctrl+B, and only Ctrl+B", () => {
+ expect(isLeaderChord(press("b", { ctrlKey: true }))).toBe(true);
+ expect(isLeaderChord(press("B", { ctrlKey: true, shiftKey: true }))).toBe(false);
+ expect(isLeaderChord(press("b", { metaKey: true }))).toBe(false);
+ expect(isLeaderChord(press("b", { ctrlKey: true, altKey: true }))).toBe(false);
+ });
+
+ it("matches the physical key, whatever the layout prints on it", () => {
+ expect(isLeaderChord({ ...press("b", { ctrlKey: true }), key: "∫" })).toBe(true);
+ });
+
+ it("passes through as the control code Ctrl+B sends", () => {
+ expect(LEADER_PASSTHROUGH).toBe(String.fromCharCode(2));
+ });
+});
+
+describe("agent letters", () => {
+ it("gives Claude C and Codex X so the two C agents never collide", () => {
+ expect(AGENTS.find((agent) => agent.name === "claude")?.key).toBe("c");
+ expect(AGENTS.find((agent) => agent.name === "codex")?.key).toBe("x");
+ });
+
+ it("never hands an agent a letter the root menu uses for a command", () => {
+ const many = assignAgentKeys("abcdefghijklmnopqrstuvwxyz".split("").map((letter) => ({ name: `${letter}-agent`, label: letter })));
+ for (const agent of many) expect(RESERVED_ROOT_KEYS.has(agent.key)).toBe(false);
+ expect(new Set(many.map((agent) => agent.key)).size).toBe(many.length);
+ });
+
+ it("gives an unknown CLI the first free letter of its own name", () => {
+ const [agent] = assignAgentKeys([{ name: "zed-agent", label: "Zed" }]);
+ expect(agent.key).toBe("d"); // z is reserved (maximize), e is reserved (even out)
+ });
+});
+
+describe("key sequences", () => {
+ it("C then → opens Claude Code to the right of the focused pane", () => {
+ const first = resolveHotkey(ROOT, press("c"), AGENTS);
+ expect(first).toEqual({ type: "step", step: { menu: "direction", agent: "claude", label: "Claude Code" } });
+ if (first.type !== "step") throw new Error("expected a step");
+ expect(resolveHotkey(first.step, press("ArrowRight"), AGENTS)).toEqual({ type: "run", action: { kind: "spawn", agent: "claude", direction: "right" } });
+ });
+
+ it("X then ↓ opens Codex below; Enter joins the even grid", () => {
+ const step: IdeHotkeyStep = { menu: "direction", agent: "codex", label: "Codex" };
+ expect(resolveHotkey(step, press("ArrowDown"), AGENTS)).toEqual({ type: "run", action: { kind: "spawn", agent: "codex", direction: "down" } });
+ expect(resolveHotkey(step, press("ArrowUp"), AGENTS)).toEqual({ type: "run", action: { kind: "spawn", agent: "codex", direction: "above" } });
+ expect(resolveHotkey(step, press("Enter"), AGENTS)).toEqual({ type: "run", action: { kind: "spawn", agent: "codex", direction: null } });
+ });
+
+ it("W then N starts a new workspace", () => {
+ const first = resolveHotkey(ROOT, press("w"), AGENTS);
+ expect(first).toEqual({ type: "step", step: { menu: "workspace" } });
+ expect(resolveHotkey({ menu: "workspace" }, press("n"), AGENTS)).toEqual({ type: "run", action: { kind: "new-workspace" } });
+ });
+
+ it("arrows focus a neighbor; Shift+arrows swap with it", () => {
+ expect(resolveHotkey(ROOT, press("ArrowLeft"), AGENTS)).toEqual({ type: "run", action: { kind: "focus-pane", direction: "left" } });
+ expect(resolveHotkey(ROOT, press("ArrowLeft", { shiftKey: true }), AGENTS)).toEqual({ type: "run", action: { kind: "swap-pane", direction: "left" } });
+ });
+
+ it("digits jump to a workspace by position, Shift+digit included", () => {
+ expect(resolveHotkey(ROOT, { ...press("!"), code: "Digit1", shiftKey: true }, AGENTS)).toEqual({ type: "run", action: { kind: "workspace-index", index: 0 } });
+ expect(resolveHotkey(ROOT, { ...press("3"), code: "Digit3" }, AGENTS)).toEqual({ type: "run", action: { kind: "workspace-index", index: 2 } });
+ });
+
+ it("Escape closes, Backspace steps back, a modifier alone waits", () => {
+ expect(resolveHotkey({ menu: "workspace" }, press("Escape"), AGENTS)).toEqual({ type: "close" });
+ expect(resolveHotkey({ menu: "workspace" }, press("Backspace"), AGENTS)).toEqual({ type: "step", step: { menu: "root" } });
+ expect(resolveHotkey(ROOT, press("Shift", { shiftKey: true }), AGENTS)).toEqual({ type: "ignore" });
+ });
+
+ it("an unknown key or a Ctrl chord closes the menu instead of hanging", () => {
+ expect(resolveHotkey(ROOT, press("j"), AGENTS)).toEqual({ type: "close" });
+ expect(resolveHotkey(ROOT, press("c", { ctrlKey: true }), AGENTS)).toEqual({ type: "close" });
+ });
+
+ it("speaks herdr's keys: V and - split, N/P switch, Shift+N/W/D manage workspaces", () => {
+ expect(resolveHotkey(ROOT, press("v"), AGENTS)).toEqual({ type: "run", action: { kind: "split", direction: "right" } });
+ expect(resolveHotkey(ROOT, { ...press("-"), code: "Minus" }, AGENTS)).toEqual({ type: "run", action: { kind: "split", direction: "down" } });
+ expect(resolveHotkey(ROOT, press("n"), AGENTS)).toEqual({ type: "run", action: { kind: "workspace-step", step: 1 } });
+ expect(resolveHotkey(ROOT, press("p"), AGENTS)).toEqual({ type: "run", action: { kind: "workspace-step", step: -1 } });
+ expect(resolveHotkey(ROOT, press("N", { shiftKey: true }), AGENTS)).toEqual({ type: "run", action: { kind: "new-workspace" } });
+ expect(resolveHotkey(ROOT, press("W", { shiftKey: true }), AGENTS)).toEqual({ type: "run", action: { kind: "rename-workspace" } });
+ expect(resolveHotkey(ROOT, press("D", { shiftKey: true }), AGENTS)).toEqual({ type: "run", action: { kind: "close-workspace" } });
+ expect(resolveHotkey(ROOT, { ...press("?"), shiftKey: true }, AGENTS)).toEqual({ type: "step", step: { menu: "help" } });
+ });
+
+ it("the mode bar names the mode and the agent letters", () => {
+ const bar = modeBar(ROOT, AGENTS);
+ expect(bar.badge).toBe("PREFIX");
+ expect(bar.hints.map((hint) => hint.keys.join("+"))).toEqual(expect.arrayContaining(["C", "X", "Esc", "?", "Ctrl+B"]));
+ expect(modeBar({ menu: "direction", agent: "codex", label: "Codex" }, AGENTS).badge).toBe("CODEX");
+ });
+
+ it("lists every agent letter and every command it accepts", () => {
+ const root = hotkeyHints(ROOT, AGENTS).flatMap((group) => group.hints.flatMap((hint) => hint.keys));
+ for (const agent of AGENTS) expect(root).toContain(agent.key.toUpperCase());
+ for (const letter of RESERVED_ROOT_KEYS) expect(root).toContain(letter.toUpperCase());
+ });
+});
+
+describe("neighborInDirection", () => {
+ // Two columns; the right column is split into two rows.
+ const boxes = [
+ { x: 0, y: 0, w: 0.5, h: 1 },
+ { x: 0.5, y: 0, w: 0.5, h: 0.5 },
+ { x: 0.5, y: 0.5, w: 0.5, h: 0.5 },
+ ];
+
+ it("finds the pane that lies in each direction", () => {
+ expect(neighborInDirection(boxes, 0, "right")).toBe(1);
+ expect(neighborInDirection(boxes, 1, "down")).toBe(2);
+ expect(neighborInDirection(boxes, 2, "up")).toBe(1);
+ expect(neighborInDirection(boxes, 2, "left")).toBe(0);
+ });
+
+ it("answers null at the edge of the grid", () => {
+ expect(neighborInDirection(boxes, 0, "left")).toBeNull();
+ expect(neighborInDirection(boxes, 1, "up")).toBeNull();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.ts b/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.ts
new file mode 100644
index 0000000000..dc294e3e8e
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/ideHotkeys.ts
@@ -0,0 +1,396 @@
+/**
+ * Leader-key shortcuts for the Agentic IDE.
+ *
+ * One chord — Ctrl+B, on every OS, like tmux — opens a small key menu; the
+ * next keys pick what happens, the way tmux and herdr work: a one-line mode
+ * bar at the bottom says PREFIX and names the keys, `?` opens the full list,
+ * Esc or any unbound key drops back to the terminal. `Ctrl+B, C, →` opens a
+ * Claude Code pane to the right of the focused pane; `Ctrl+B, V` splits the
+ * focused pane with the same agent; `Ctrl+B, W, N` starts a new workspace.
+ *
+ * Why a leader and not a chord per action: a focused pane forwards nearly every
+ * Ctrl chord to the coding agent running in it, and each agent claims its own
+ * (Claude Code alone uses Ctrl+B, Ctrl+G, Ctrl+O, Ctrl+R, Ctrl+T). One reserved
+ * chord leaves every other key with the agent. The one it takes, Ctrl+B, is
+ * Claude Code's "run in background": pressing it twice types it into the pane
+ * (`LEADER_PASSTHROUGH`), exactly as tmux passes its prefix through.
+ *
+ * Everything here is pure: the hook (`useIdeHotkeys`) feeds key events in and
+ * carries out the actions that come back, so the whole key map is testable
+ * without a DOM.
+ */
+import type { PaneSplitDirection } from "./WorkspaceTerminalHeader";
+
+export type PaneDirection = "left" | "right" | "up" | "down";
+
+/** What a finished key sequence asks the IDE to do. */
+export type IdeHotkeyAction =
+ | { kind: "spawn"; agent: string; direction: PaneSplitDirection | null }
+ | { kind: "agent-picker" }
+ | { kind: "split"; direction: PaneSplitDirection }
+ | { kind: "focus-pane"; direction: PaneDirection }
+ | { kind: "swap-pane"; direction: PaneDirection }
+ | { kind: "maximize-pane" }
+ | { kind: "close-pane" }
+ | { kind: "rename-pane" }
+ | { kind: "fork-pane" }
+ | { kind: "balance" }
+ | { kind: "toggle-voice" }
+ | { kind: "workspace-index"; index: number }
+ | { kind: "workspace-step"; step: 1 | -1 }
+ | { kind: "new-workspace" }
+ | { kind: "new-worktree-workspace" }
+ | { kind: "rename-workspace" }
+ | { kind: "close-workspace" }
+ | { kind: "git-panel" }
+ | { kind: "workspace-options" }
+ | { kind: "connect-project" };
+
+/** Where in a key sequence the menu stands. */
+export type IdeHotkeyStep =
+ | { menu: "root" }
+ | { menu: "workspace" }
+ | { menu: "help" }
+ | { menu: "direction"; agent: string; label: string };
+
+/** The minimal slice of a KeyboardEvent the matcher reads. */
+export interface HotkeyEventLike {
+ key: string;
+ code: string;
+ ctrlKey: boolean;
+ metaKey: boolean;
+ altKey: boolean;
+ shiftKey: boolean;
+}
+
+/** An agent the menu can open, already filtered to what this machine can run. */
+export interface HotkeyAgent { name: string; label: string }
+
+/** One agent and the letter that opens it. */
+export interface AgentKey extends HotkeyAgent { key: string }
+
+/** The result of one key press while the menu is open. */
+export type HotkeyOutcome =
+ | { type: "step"; step: IdeHotkeyStep }
+ | { type: "run"; action: IdeHotkeyAction }
+ | { type: "close" }
+ | { type: "ignore" };
+
+/**
+ * Is this the leader chord? Ctrl+B on every OS — Ctrl, not Cmd, on a Mac too,
+ * because that is the terminal key tmux users already have in their hands.
+ */
+export function isLeaderChord(event: HotkeyEventLike): boolean {
+ // `code` first: it names the physical key on every layout. `key` covers a
+ // host that reports no code (some remote-desktop and test events do).
+ const isB = event.code === "KeyB" || (!event.code && event.key.toLowerCase() === "b");
+ return event.ctrlKey && !event.metaKey && !event.shiftKey && !event.altKey && isB;
+}
+
+/** What Ctrl+B twice types into the focused pane: the control code Ctrl+B itself sends. */
+export const LEADER_PASSTHROUGH = "\x02";
+
+/** Letters the root menu keeps for its own commands; no agent may take one. */
+export const RESERVED_ROOT_KEYS = new Set(["e", "f", "m", "n", "p", "q", "r", "v", "w", "z"]);
+
+/**
+ * The letter each known agent prefers. Claude and Codex both start with C, so
+ * Codex takes the X of its name — the same split its own docs and most
+ * launchers use. A CLI added later falls through to the first free letter of
+ * its own name (see `assignAgentKeys`).
+ */
+const PREFERRED_AGENT_KEYS: Record<string, string> = {
+ claude: "c",
+ codex: "x",
+ cursor: "u",
+ opencode: "o",
+ kimi: "k",
+ glm: "l",
+ "grok-build": "g",
+ antigravity: "a",
+ gemini: "i",
+ "deepseek-harness": "d",
+};
+
+/**
+ * Give every agent its own letter, stable across sessions.
+ *
+ * Known agents keep their preferred letter; the rest take the first unused
+ * letter of their name, then of their label, then of the alphabet. An agent
+ * that finds no letter at all is left out rather than given a key that does
+ * something else.
+ */
+export function assignAgentKeys(agents: readonly HotkeyAgent[]): AgentKey[] {
+ const taken = new Set(RESERVED_ROOT_KEYS);
+ const assigned = new Map<string, string>();
+ for (const agent of agents) {
+ const preferred = PREFERRED_AGENT_KEYS[agent.name];
+ if (preferred && !taken.has(preferred)) { assigned.set(agent.name, preferred); taken.add(preferred); }
+ }
+ for (const agent of agents) {
+ if (assigned.has(agent.name)) continue;
+ const candidates = `${agent.name}${agent.label}abcdefghijklmnopqrstuvwxyz`.toLowerCase().replace(/[^a-z]/g, "");
+ const letter = [...candidates].find((char) => !taken.has(char));
+ if (letter) { assigned.set(agent.name, letter); taken.add(letter); }
+ }
+ return agents.flatMap((agent) => {
+ const key = assigned.get(agent.name);
+ return key ? [{ ...agent, key }] : [];
+ });
+}
+
+const ARROWS: Record<string, PaneDirection> = {
+ ArrowLeft: "left", ArrowRight: "right", ArrowUp: "up", ArrowDown: "down",
+};
+
+/** Arrow → the split direction the add-agent API speaks. */
+const SPLIT_FOR_ARROW: Record<PaneDirection, PaneSplitDirection> = {
+ left: "left", right: "right", up: "above", down: "down",
+};
+
+/** Pure modifier presses never move the menu; the user is still building a chord. */
+const MODIFIER_KEYS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "OS"]);
+
+/** The letter a key event typed, layout-aware: QWERTZ users see their own Z. */
+function letterOf(event: HotkeyEventLike): string | null {
+ const key = event.key.length === 1 ? event.key.toLowerCase() : "";
+ return /^[a-z]$/.test(key) ? key : null;
+}
+
+/** The digit 1–9 of a number-row or numpad key, by position (Shift+1 is "!" on most layouts). */
+function digitOf(event: HotkeyEventLike): number | null {
+ const match = /^(?:Digit|Numpad)([1-9])$/.exec(event.code) ?? /^([1-9])$/.exec(event.key);
+ return match ? Number(match[1]) : null;
+}
+
+/**
+ * Advance the menu by one key press.
+ *
+ * Escape closes from anywhere; Backspace steps back one level. A key the
+ * current menu does not know closes it too, so a stray press never leaves the
+ * IDE waiting for input the user no longer means to give.
+ */
+export function resolveHotkey(step: IdeHotkeyStep, event: HotkeyEventLike, agents: readonly AgentKey[]): HotkeyOutcome {
+ if (MODIFIER_KEYS.has(event.key)) return { type: "ignore" };
+ if (event.key === "Escape") return { type: "close" };
+ if (event.key === "Backspace") return step.menu === "root" ? { type: "close" } : { type: "step", step: { menu: "root" } };
+ // The full key list: any key leaves it, the way herdr's prefix+? help does.
+ if (step.menu === "help") return { type: "close" };
+ // Ctrl/Cmd/Alt combinations belong to the app and the OS, never to the menu.
+ if (event.ctrlKey || event.metaKey || event.altKey) return { type: "close" };
+ const arrow = ARROWS[event.key];
+ const letter = letterOf(event);
+
+ if (step.menu === "direction") {
+ if (arrow) return { type: "run", action: { kind: "spawn", agent: step.agent, direction: SPLIT_FOR_ARROW[arrow] } };
+ if (event.key === "Enter" || event.key === " ") return { type: "run", action: { kind: "spawn", agent: step.agent, direction: null } };
+ return { type: "close" };
+ }
+
+ if (step.menu === "workspace") {
+ const workspaceKeys: Record<string, IdeHotkeyAction> = {
+ n: { kind: "new-workspace" },
+ t: { kind: "new-worktree-workspace" },
+ r: { kind: "rename-workspace" },
+ q: { kind: "close-workspace" },
+ g: { kind: "git-panel" },
+ o: { kind: "workspace-options" },
+ p: { kind: "connect-project" },
+ };
+ if (letter && workspaceKeys[letter]) return { type: "run", action: workspaceKeys[letter] };
+ if (arrow === "right" || arrow === "down") return { type: "run", action: { kind: "workspace-step", step: 1 } };
+ if (arrow === "left" || arrow === "up") return { type: "run", action: { kind: "workspace-step", step: -1 } };
+ const digit = digitOf(event);
+ if (digit) return { type: "run", action: { kind: "workspace-index", index: digit - 1 } };
+ return { type: "close" };
+ }
+
+ // Root menu.
+ if (arrow) return { type: "run", action: { kind: event.shiftKey ? "swap-pane" : "focus-pane", direction: arrow } };
+ if (event.key === "Tab") return { type: "run", action: { kind: "workspace-step", step: event.shiftKey ? -1 : 1 } };
+ if (event.key === "?") return { type: "step", step: { menu: "help" } };
+ if (event.key === "+") return { type: "run", action: { kind: "agent-picker" } };
+ if (event.key === "-") return { type: "run", action: { kind: "split", direction: "down" } };
+ const digit = digitOf(event);
+ if (digit) return { type: "run", action: { kind: "workspace-index", index: digit - 1 } };
+ // herdr's capital workspace keys: Shift+N new, Shift+W rename, Shift+D close.
+ if (letter && event.shiftKey) {
+ const shifted: Record<string, IdeHotkeyAction> = {
+ n: { kind: "new-workspace" }, w: { kind: "rename-workspace" }, d: { kind: "close-workspace" },
+ };
+ return shifted[letter] ? { type: "run", action: shifted[letter] } : { type: "close" };
+ }
+ if (letter) {
+ const rootKeys: Record<string, IdeHotkeyAction | IdeHotkeyStep> = {
+ e: { kind: "balance" },
+ f: { kind: "fork-pane" },
+ m: { kind: "toggle-voice" },
+ n: { kind: "workspace-step", step: 1 },
+ p: { kind: "workspace-step", step: -1 },
+ q: { kind: "close-pane" },
+ r: { kind: "rename-pane" },
+ v: { kind: "split", direction: "right" },
+ w: { menu: "workspace" },
+ z: { kind: "maximize-pane" },
+ };
+ const command = rootKeys[letter];
+ if (command) return "menu" in command ? { type: "step", step: command } : { type: "run", action: command };
+ const agent = agents.find((entry) => entry.key === letter);
+ if (agent) return { type: "step", step: { menu: "direction", agent: agent.name, label: agent.label } };
+ }
+ return { type: "close" };
+}
+
+/** The one-line mode bar: a badge naming the mode, then the keys that work in it. */
+export interface ModeBar { badge: string; hints: HotkeyHint[] }
+
+/** What the bar at the bottom says for a step; the full list lives behind `?`. */
+export function modeBar(step: IdeHotkeyStep, agents: readonly AgentKey[]): ModeBar {
+ if (step.menu === "direction") {
+ return {
+ badge: step.label.toUpperCase(),
+ hints: [
+ { keys: ["→"], label: "right" }, { keys: ["←"], label: "left" }, { keys: ["↑"], label: "above" },
+ { keys: ["↓"], label: "below" }, { keys: ["Enter"], label: "even grid" }, { keys: ["Esc"], label: "cancel" },
+ ],
+ };
+ }
+ if (step.menu === "workspace") {
+ return {
+ badge: "WORKSPACE",
+ hints: [
+ { keys: ["N"], label: "new" }, { keys: ["T"], label: "worktree" }, { keys: ["R"], label: "rename" },
+ { keys: ["Q"], label: "close" }, { keys: ["G"], label: "git" }, { keys: ["O"], label: "options" },
+ { keys: ["P"], label: "connect folder" }, { keys: ["←→"], label: "switch" }, { keys: ["Esc"], label: "back" },
+ ],
+ };
+ }
+ if (step.menu === "help") return { badge: "KEYS", hints: [{ keys: ["any key"], label: "close" }] };
+ return {
+ badge: "PREFIX",
+ hints: [
+ ...agents.map((agent) => ({ keys: [agent.key.toUpperCase()], label: agent.label })),
+ { keys: ["V", "-"], label: "split" },
+ { keys: ["←↑→↓"], label: "move" },
+ { keys: ["Z"], label: "zoom" },
+ { keys: ["Q"], label: "close" },
+ { keys: ["W"], label: "workspaces" },
+ { keys: ["?"], label: "all keys" },
+ { keys: ["Esc"], label: "cancel" },
+ { keys: ["Ctrl", "B"], label: "send Ctrl+B" },
+ ],
+ };
+}
+
+/** One row of the key menu as the overlay draws it. */
+export interface HotkeyHint { keys: string[]; label: string }
+export interface HotkeyHintGroup { title: string; hints: HotkeyHint[] }
+
+/** The rows the overlay shows for a step — the same table `resolveHotkey` reads. */
+export function hotkeyHints(step: IdeHotkeyStep, agents: readonly AgentKey[]): HotkeyHintGroup[] {
+ if (step.menu === "direction") {
+ return [{
+ title: `Open ${step.label}`,
+ hints: [
+ { keys: ["→"], label: "To the right" },
+ { keys: ["←"], label: "To the left" },
+ { keys: ["↑"], label: "Above" },
+ { keys: ["↓"], label: "Below" },
+ { keys: ["Enter"], label: "Even grid" },
+ ],
+ }];
+ }
+ if (step.menu === "workspace") {
+ return [{
+ title: "Workspace",
+ hints: [
+ { keys: ["N"], label: "New workspace" },
+ { keys: ["T"], label: "New worktree workspace" },
+ { keys: ["R"], label: "Rename workspace" },
+ { keys: ["Q"], label: "Close workspace" },
+ { keys: ["G"], label: "Git panel" },
+ { keys: ["O"], label: "Workspace options" },
+ { keys: ["P"], label: "Connect a project folder" },
+ { keys: ["←", "→"], label: "Previous / next workspace" },
+ { keys: ["1–9"], label: "Go to workspace 1–9" },
+ ],
+ }];
+ }
+ return [
+ {
+ title: "New pane",
+ hints: [
+ ...agents.map((agent) => ({ keys: [agent.key.toUpperCase()], label: `${agent.label}, then an arrow` })),
+ { keys: ["V"], label: "Split right, same agent" },
+ { keys: ["-"], label: "Split below, same agent" },
+ { keys: ["+"], label: "Choose agent…" },
+ ],
+ },
+ {
+ title: "Panes",
+ hints: [
+ { keys: ["←↑→↓"], label: "Focus neighbor" },
+ { keys: ["Shift", "←↑→↓"], label: "Swap with neighbor" },
+ { keys: ["Z"], label: "Maximize / restore" },
+ { keys: ["R"], label: "Rename pane" },
+ { keys: ["F"], label: "Fork pane" },
+ { keys: ["Q"], label: "Close pane" },
+ { keys: ["E"], label: "Even out layout" },
+ ],
+ },
+ {
+ title: "Workspaces",
+ hints: [
+ { keys: ["W"], label: "Workspace menu…" },
+ { keys: ["1–9"], label: "Go to workspace" },
+ { keys: ["N", "P"], label: "Next / previous workspace" },
+ { keys: ["Shift", "N"], label: "New workspace" },
+ { keys: ["Shift", "W"], label: "Rename workspace" },
+ { keys: ["Shift", "D"], label: "Close workspace" },
+ { keys: ["M"], label: "Voice bubble" },
+ { keys: ["Ctrl", "B"], label: "Send Ctrl+B to the pane" },
+ ],
+ },
+ ];
+}
+
+/**
+ * The pane that lies in `direction` from `from`, on a grid of boxes in 0–1
+ * coordinates: nearest by centre along the axis, overlapping across it, ties
+ * broken by how close the centres sit across the axis.
+ */
+export interface PaneBox { x: number; y: number; w: number; h: number }
+export function neighborInDirection(boxes: readonly (PaneBox | undefined)[], from: number, direction: PaneDirection): number | null {
+ const box = boxes[from];
+ if (!box) return null;
+ const horizontal = direction === "left" || direction === "right";
+ const sign = direction === "left" || direction === "up" ? -1 : 1;
+ const centre = horizontal ? box.x + box.w / 2 : box.y + box.h / 2;
+ const crossCentre = horizontal ? box.y + box.h / 2 : box.x + box.w / 2;
+ let best: { index: number; distance: number; cross: number } | null = null;
+ boxes.forEach((other, index) => {
+ if (!other || index === from) return;
+ const distance = ((horizontal ? other.x + other.w / 2 : other.y + other.h / 2) - centre) * sign;
+ const overlap = horizontal
+ ? Math.min(box.y + box.h, other.y + other.h) - Math.max(box.y, other.y)
+ : Math.min(box.x + box.w, other.x + other.w) - Math.max(box.x, other.x);
+ if (distance <= 0.001 || overlap <= 0.001) return;
+ const cross = Math.abs((horizontal ? other.y + other.h / 2 : other.x + other.w / 2) - crossCentre);
+ if (!best || distance < best.distance || (distance === best.distance && cross < best.cross)) best = { index, distance, cross };
+ });
+ return best ? (best as { index: number }).index : null;
+}
+
+/** The window event that carries a pane command from the key menu to the grid that owns the pane. */
+export const PANE_COMMAND_EVENT = "jarvis:ide-pane-command";
+export type PaneCommand =
+ | { kind: "focus"; direction: PaneDirection }
+ | { kind: "swap"; direction: PaneDirection }
+ | { kind: "maximize" }
+ | { kind: "fork" }
+ | { kind: "rename"; name: string };
+export interface PaneCommandDetail { workspaceId: string; pane: string; command: PaneCommand }
+
+/** The window event that types text into one pane's terminal, as if from the keyboard. */
+export const PANE_INPUT_EVENT = "jarvis:ide-pane-input";
+export interface PaneInputDetail { workspaceId: string; pane: string; data: string }
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.json
index 798c5046cd..f369c9975b 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json
@@ -1620,7 +1620,8 @@
"zoom_in": "Terminaltext größer",
"zoom_out": "Terminaltext kleiner",
"zoom_reset": "Terminaltextgröße zurücksetzen",
- "open_overlay": "Diese Liste öffnen"
+ "open_overlay": "Diese Liste öffnen",
+ "ide_menu": "Tastenmenü der Agentic IDE (zweimal: Strg+B an das Fenster)"
}
},
"board_view": {
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.json
index be106b5245..8a8b184e90 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json
@@ -1620,7 +1620,8 @@
"zoom_in": "Larger terminal text",
"zoom_out": "Smaller terminal text",
"zoom_reset": "Reset terminal text size",
- "open_overlay": "Open this list"
+ "open_overlay": "Open this list",
+ "ide_menu": "Agentic IDE key menu (twice: Ctrl+B to the pane)"
}
},
"board_view": {
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.json
index 1c7dac49c3..846f2e43d4 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json
@@ -1620,7 +1620,8 @@
"zoom_in": "Texto del terminal más grande",
"zoom_out": "Texto del terminal más pequeño",
"zoom_reset": "Restablecer el tamaño del texto",
- "open_overlay": "Abrir esta lista"
+ "open_overlay": "Abrir esta lista",
+ "ide_menu": "Menú de teclas del IDE agéntico (dos veces: Ctrl+B al panel)"
}
},
"board_view": {
diff --git a/jarvis/ui/web/frontend/src/lib/shortcutRegistry.test.ts b/jarvis/ui/web/frontend/src/lib/shortcutRegistry.test.ts
index 005cacbe98..b13799b5fe 100644
--- a/jarvis/ui/web/frontend/src/lib/shortcutRegistry.test.ts
+++ b/jarvis/ui/web/frontend/src/lib/shortcutRegistry.test.ts
@@ -9,6 +9,7 @@
*/
import { describe, expect, it } from "vitest";
import { zoomIntentFor } from "@/components/agentic/terminalZoom";
+import { isLeaderChord } from "@/components/agentic/ideHotkeys";
import {
SHORTCUTS,
SHORTCUT_AREAS,
@@ -102,6 +103,19 @@ describe("fixed chords agree with the matcher that implements them", () => {
});
});
+describe("the IDE key menu chord", () => {
+ for (const isMac of [true, false]) {
+ it(`opens the menu on ${isMac ? "macOS" : "PC"} exactly as declared`, () => {
+ const entry = shortcutsForArea("workspace").find(
+ (s) => s.labelKey === "shortcut_overlay.workspace.ide_menu",
+ ) as FixedShortcut;
+ expect(entry.keys).toEqual(["Ctrl", "B"]);
+ expect(keyLabel(entry.keys[0], isMac)).toBe("Ctrl");
+ expect(isLeaderChord({ key: "b", code: "KeyB", ctrlKey: true, metaKey: false, altKey: false, shiftKey: false })).toBe(true);
+ });
+ }
+});
+
describe("keyLabel", () => {
it("draws the platform modifier the way each keyboard prints it", () => {
expect(keyLabel("Mod", true)).toBe("⌘");
diff --git a/jarvis/ui/web/frontend/src/lib/shortcutRegistry.ts b/jarvis/ui/web/frontend/src/lib/shortcutRegistry.ts
index 8f47cf58e7..f3f803b246 100644
--- a/jarvis/ui/web/frontend/src/lib/shortcutRegistry.ts
+++ b/jarvis/ui/web/frontend/src/lib/shortcutRegistry.ts
@@ -103,6 +103,12 @@ export const SHORTCUTS: readonly Shortcut[] = [
keys: ["?"],
labelKey: "shortcut_overlay.workspace.open_overlay",
},
+ {
+ kind: "fixed",
+ area: "workspace",
+ keys: ["Ctrl", "B"],
+ labelKey: "shortcut_overlay.workspace.ide_menu",
+ },
] as const;
/** Areas in the order the overlay renders them. */
diff --git a/jarvis/ui/web/frontend/src/views/AgenticIdeView.test.tsx b/jarvis/ui/web/frontend/src/views/AgenticIdeView.test.tsx
index b941b009d4..b5a7d1b04b 100644
--- a/jarvis/ui/web/frontend/src/views/AgenticIdeView.test.tsx
+++ b/jarvis/ui/web/frontend/src/views/AgenticIdeView.test.tsx
@@ -178,6 +178,23 @@ describe("Agentic IDE project flow", () => {
expect(api.reorderIdeTerminals).not.toHaveBeenCalled();
});
+ it("Ctrl+B, X, then an arrow opens Codex beside the selected pane", async () => {
+ const terminals = [{ key: "t1", history_id: "id1", name: "T1", display_name: "Codex" }, { key: "t2", history_id: "id2", name: "T2", display_name: "Codex" }];
+ const session = { id: "w1", project_id: "p1", folder: "/code/app", name: "App work", created_at: 0,
+ focus_mode: false, project: { name: "App" }, terminals, layout: balancedLayout(["t1", "t2"]) };
+ api.fetchIdeState.mockResolvedValue({ ...emptyState, active: true, active_id: "w1", session });
+ api.fetchIdeProjects.mockResolvedValue({ projects: [project], active_workspace_id: "w1" });
+ api.addTerminal.mockResolvedValue(session);
+ render(<AgenticIdeView />);
+ await screen.findByRole("button", { name: "Pane add" });
+ await waitFor(() => expect(api.fetchIdeAgents).toHaveBeenCalled());
+ fireEvent.keyDown(document.body, { key: "b", code: "KeyB", ctrlKey: true });
+ expect(await screen.findByRole("dialog", { name: "IDE shortcuts" })).toBeTruthy();
+ fireEvent.keyDown(document.body, { key: "x", code: "KeyX" });
+ fireEvent.keyDown(document.body, { key: "ArrowRight", code: "ArrowRight" });
+ await waitFor(() => expect(api.addTerminal).toHaveBeenCalledWith({ workspace_id: "w1", agent: "codex", anchor: "T1", direction: "right" }, { onMessage: expect.any(Function) }));
+ });
+
it("shows the pane count and refuses a new agent once the workspace is full", async () => {
const terminals = Array.from({ length: 16 }, (_, index) => ({ key: `t${index}`, history_id: `id${index}`, name: `T${index}`, display_name: "Codex" }));
const session = { id: "w1", project_id: "p1", folder: "/code/app", name: "App work", created_at: 0,
diff --git a/jarvis/ui/web/frontend/src/views/AgenticIdeView.tsx b/jarvis/ui/web/frontend/src/views/AgenticIdeView.tsx
index 80e54e20c7..2cc0b623be 100644
--- a/jarvis/ui/web/frontend/src/views/AgenticIdeView.tsx
+++ b/jarvis/ui/web/frontend/src/views/AgenticIdeView.tsx
@@ -12,6 +12,8 @@ import { IdeSidePanelFrame } from "@/components/agentic/sidePanel/IdeSidePanel";
import { GRID_LIMIT_HINT, MAX_WORKSPACE_PANES, canSplitFit, fitsWorkspace, isBalancedWorkspace } from "@/components/agentic/workspaceDocking";
import { AgentMark } from "@/components/agentic/AgentMark";
import { CloseAgentDialog, type CloseTarget } from "@/components/agentic/CloseAgentDialog";
+import { IdeHotkeyMenu } from "@/components/agentic/IdeHotkeyMenu";
+import { LEADER_PASSTHROUGH, PANE_COMMAND_EVENT, PANE_INPUT_EVENT, type IdeHotkeyAction, type PaneCommand, type PaneCommandDetail, type PaneInputDetail } from "@/components/agentic/ideHotkeys";
import { GitCheckoutPicker } from "@/components/agentic/git/GitCheckoutPicker";
import { GitPanelDialog } from "@/components/agentic/git/GitPanelDialog";
import { KEEP_CHECKOUT, prepareGit, type GitPlan } from "@/lib/gitApi";
@@ -465,6 +467,79 @@ export function AgenticIdeView({ onScreen = true }: AgenticIdeViewProps) {
const stopWorkspace = () => {
if (session) setCloseRequest({ kind: "workspace", workspaceId: session.id });
};
+ // Ctrl+B, then a key (see components/agentic/ideHotkeys): the IDE's
+ // key menu. Pane commands go to the grid that owns the pane; the rest are
+ // the same calls the buttons and the sidebar make.
+ const hotkeysEnabled = onScreen && !dialogOpen && !optionsOpen && !gitOpen && !closeRequest;
+ const hotkeyAgents = installed.map((agent) => ({ name: agent.name, label: agent.display_name }));
+ const sendPaneCommand = (command: PaneCommand) => {
+ if (!session || !selected) return;
+ const detail: PaneCommandDetail = { workspaceId: session.id, pane: selected, command };
+ window.dispatchEvent(new CustomEvent(PANE_COMMAND_EVENT, { detail }));
+ };
+ const openWorkspaces = state?.workspaces ?? [];
+ const goToWorkspace = (index: number) => {
+ const target = openWorkspaces[index];
+ if (!target) { pushToast("info", `There is no workspace ${index + 1}.`); return; }
+ if (target.id !== session?.id) void activateFromTree(target.id);
+ };
+ const runHotkey = (hotkey: IdeHotkeyAction): void => {
+ switch (hotkey.kind) {
+ case "split": {
+ // tmux/herdr split: the new pane runs what the focused pane runs.
+ const focused = session?.terminals.find((terminal) => terminal.name === selected);
+ const agent = focused?.agent ?? installed[0]?.name;
+ if (!agent) { openAgentPicker(); return; }
+ runHotkey({ kind: "spawn", agent, direction: hotkey.direction });
+ return;
+ }
+ case "spawn": {
+ if (!session) { setProjectDialog(true); return; }
+ if (session.terminals.length >= maxPanes) { pushToast("error", `This workspace is full (${maxPanes} agents). Close a pane, or open another workspace.`); return; }
+ const anchor = session.terminals.find((terminal) => terminal.name === selected);
+ const fits = Boolean(anchor && hotkey.direction && canSplitFit(session.layout, session.terminals, anchor.key, hotkey.direction, maxPanes));
+ if (anchor && hotkey.direction && !fits) pushToast("info", `No room beside ${anchor.name} there; the new agent joins the even grid.`);
+ addAgent(hotkey.agent, session.id, fits ? anchor!.name : undefined, fits ? hotkey.direction! : "down",
+ anchor ? anchor.computer_id || null : workspaceRunsOn(session.terminals));
+ return;
+ }
+ case "agent-picker": openAgentPicker(); return;
+ case "focus-pane": sendPaneCommand({ kind: "focus", direction: hotkey.direction }); return;
+ case "swap-pane": sendPaneCommand({ kind: "swap", direction: hotkey.direction }); return;
+ case "maximize-pane": sendPaneCommand({ kind: "maximize" }); return;
+ case "fork-pane": sendPaneCommand({ kind: "fork" }); return;
+ case "rename-pane": return; // the menu asks for the name itself
+ case "close-pane": {
+ const terminal = session?.terminals.find((entry) => entry.name === selected);
+ if (terminal) closeAgent(terminal);
+ return;
+ }
+ case "balance": balanceLayout(); return;
+ case "toggle-voice": setVoiceOpen((current) => { const next = !current; storeVoiceBubbleOpen(next); return next; }); return;
+ case "workspace-index": goToWorkspace(hotkey.index); return;
+ case "workspace-step": {
+ if (openWorkspaces.length < 2) return;
+ const at = Math.max(0, openWorkspaces.findIndex((workspace) => workspace.id === session?.id));
+ goToWorkspace((at + hotkey.step + openWorkspaces.length) % openWorkspaces.length);
+ return;
+ }
+ case "new-workspace": {
+ const project = projects.find((entry) => entry.id === session?.project_id);
+ if (!project) { setProjectDialog(true); return; }
+ setWorkspaceProject(project); setWorkspaceName(""); setWorkspaceAgents([installed[0]?.name ?? ""]);
+ setWorkspaceGit(KEEP_CHECKOUT); setWorkspaceComputer(storedRunOn(project.id));
+ return;
+ }
+ case "new-worktree-workspace": newWorktreeWorkspace(); return;
+ case "rename-workspace":
+ if (session) { setRenameValue(session.name ?? session.project.name); setRenameOpen(true); }
+ return;
+ case "close-workspace": stopWorkspace(); return;
+ case "git-panel": if (session) setGitOpen(true); return;
+ case "workspace-options": if (session) setOptionsOpen(true); return;
+ case "connect-project": setProjectDialog(true); return;
+ }
+ };
const closeTarget: CloseTarget | null = !closeRequest ? null
: closeRequest.kind === "terminal"
? { kind: "terminal", name: closeRequest.terminal.name, agent: closeRequest.terminal.agent, displayName: closeRequest.terminal.display_name }
@@ -498,6 +573,13 @@ export function AgenticIdeView({ onScreen = true }: AgenticIdeViewProps) {
</IdeSidePanelFrame>
</main>
+ <IdeHotkeyMenu enabled={hotkeysEnabled} agents={hotkeyAgents} pane={session ? selected : ""} onAction={runHotkey}
+ onRenamePane={(name) => sendPaneCommand({ kind: "rename", name })}
+ onPassThrough={() => {
+ if (!session || !selected) return;
+ const detail: PaneInputDetail = { workspaceId: session.id, pane: selected, data: LEADER_PASSTHROUGH };
+ window.dispatchEvent(new CustomEvent(PANE_INPUT_EVENT, { detail }));
+ }} />
<VoiceBubble open={voiceOpen} onClose={closeVoice} onScreen={onScreen} onJumpToPane={jumpToPane} promptTarget={selected} />
{agentPicker && <div className="fixed inset-0 z-[80] flex items-center justify-center bg-background/75 p-4 backdrop-blur-sm"