Keyboard map

Panel management

The sidebar is application chrome and is not moved or maximized, or closed by these commands.

See Panel interactions for visual examples of panel selection, movement, nested layouts, split flipping, and resizing.

The Status Bar names the current interaction level. In PANE, unmodified input belongs to the focused surface and directional focus is explicit. In PANEL, keys select and arrange panes; enter or escape returns to PANE.

The 1…9 column addresses follow the screen, not fixed pane kinds: alt+2 is whatever column sits directly right of the projects sidebar. alt works in any terminal; the cmd variants, like cmd+e, require a kitty-protocol terminal that reports Command as Super. The fixed pane destinations live in PANEL mode (shift+escape, then 1…6).

In PANE, clicking a pane focuses it and dragging a shared border resizes it. Bare arrows remain inside the focused surface and stop at its boundaries; they do not move focus between panes. alt+shift+arrow is the explicit spatial focus gesture and is a no-op when there is no pane in that direction.

Escape guard

Because escape both leaves PANEL mode and interrupts an agent, a slip right after dropping into a pane could cancel a turn in progress. Entering an agent pane arms a one-keypress guard: if the pane's agent is mid-turn (working, or waiting on you) and the first key pressed is a bare escape, Hocket asks before forwarding it — enter interrupts the agent, escape cancels and keeps the guard armed, so an accidental esc-mash only reopens the question. Any other first key disarms the guard. Idle agents and plain terminals receive escape immediately.

Selecting a project, worktree, branch, or session never creates a Files pane. When Files is already open it follows the sidebar selection; when it is closed, create it explicitly with f in PANEL mode, just like any other pane.

Enter on an agent session selects that session and moves to the agent pane it represents. If the active saved Panel does not yet contain that pane, Hocket opens it there; the other saved Panels are unchanged. Clicking a session is browse-first: it selects the session without changing pane membership or moving focus to the agent pane.

Every buffer opens locked: the full editor renders (selection, minimap, find, git gutter) but nothing mutates and no cursor blinks. Alt-click the buffer's tab three times to unlock it — the tab title turns green and the file takes edits; the same ritual re-locks it. The unlock is per file and dies with the tab.

With an unmounted local branch selected, explicitly opening Files shows its Git-backed tree. These buffers can never be unlocked (the ritual answers "not able to edit"); added, modified, and deleted paths are marked relative to the branch's merge-base with trunk.

While Projects has pane focus, alt+up/down moves the selected project in manual order. In panel-selection mode the same chord keeps its panel-management meaning. See Project sorting for drag ordering and recent sort modes.

Closing is panel-aware:

• Terminal: closes the active session.
• File tree: hides the tree without closing editor buffers.
• Editor: closes the active buffer.
• Graph or processes: hides only that utility panel. Opening either utility is additive: terminal, graph, and processes remain open until explicitly closed.

Open panels use an Omarchy-style adaptive split tree. A split is side by side when its region is wide and top to bottom when it is tall; opening a panel splits the focused tile. j in panel mode inverts that choice for the selected panel's parent split. Files remains attached to Editor as its inner split. The open-panel set and arrangement are universal and stay in place while navigating between worktrees or selecting a different existing agent. Agent selection changes the terminal's content without reopening or focusing it; pressing Enter on the selected sidebar session is the explicit command that opens and focuses its agent pane.

When either axis cannot preserve a useful body, Hocket switches to a stacked overflow layout: inactive panels retain a three-row title and the focused panel receives the remaining space. The underlying tree remains intact and returns when the terminal grows.

Action undo

alt+z undoes the most recent reversible application action. It is global, so it still works while a live terminal has focus. Panel moves and resizes, fullscreen changes, line-wrap changes, and notification toggles participate in the same last-in-first-out history. Actions that cross the application boundary or destroy resources—such as spawning or killing a process, saving a file, or quitting—do not claim to be undoable and do not erase the previous reversible entry. When the history is empty, alt+z is a no-op.

Undo restores the state captured by that action; it is not redo, and taking an action after undo does not replay the undone action. Editor text editing retains the editor widget's own text history independently of this application-action history.

The status bar teaches ⌥move · j flip · = even while panel-selection mode is active. Outside it, the compact legend retains close and fullscreen without advertising an inactive resize chord. ⌥ means Alt/Option.

While fullscreen is active, a highlighted bar across the top reads FULLSCREEN … with shift-esc restore at the far edge. Terminal fullscreen also sends the new viewport dimensions directly to the PTY so full-screen terminal apps redraw instead of leaving unused rows below their previous layout. Fullscreen owns the complete workspace—the fixed sidebar is hidden until restore.

Global application commands

While a live terminal is focused, ctrl+c and ctrl+d belong exclusively to the embedded process. They may stop or exit the agent, but never quit Hocket; ctrl+q is the application quit command.

Visual filter

The Projects sidebar, Git graph, and Processes pane are projections of one project/worktree context (see Context projections). Pinning that context is the visual filter: every projection dims what falls outside the pin — rows are never pruned, unlike the transient type-to-filter query.

alt+tab reads the focused projection — Projects, Git graph, or Processes — and pins the selected project, worktree, or branch. From a terminal or agent session it pins that session's owning worktree, even while the inner program is live. Inside Recent (cmd+e) it pins the highlighted row's owning worktree — session and file rows alike — without closing the list, so the projections dim live behind the browse. From any other focus it pins the sidebar selection, the join every projection follows. While pinned, arrow navigation and clicks move the pin with the selection — Recent's walk included; the status bar names the pin and teaches the exit. Esc-dismissing Recent rewinds that drift to the last deliberate pin (the one standing at open, or the one alt+tab set inside the list); enter keeps the walk's landing.

The pointer gesture is unchanged: clicking an already-selected worktree, branch, or session row pins its context, and clicking the pinned row again clears it. alt+tab is the keyboard-only equivalent, and — because a keypress has no expand/collapse conflict — it can also pin a project folder row, dimming every other project.

Hocket reserves alt+tab globally, including inside live terminal and agent sessions. Some Windows and Linux desktop environments reserve Alt-Tab for application switching and may intercept it before Hocket can receive it.

Editor and file tree

Printable text filters the sidebar, file tree, and Processes while a list has focus. In the file tree, a leading :m :a :d :u :c :g token restricts the filter to files in that git state (modified / added / deleted / untracked / conflicted / any change) and composes with the fuzzy query: :m auth is modified files matching "auth" (ADR-0021). In Processes, : lists TCP listeners and :3000 narrows to a port. Use escape to clear the filter or back out of its current scope. In the Projects sidebar, cmd+c copies the selected worktree or branch name. backspace on a selected project asks to remove it from Hocket — the same action as right-click → Remove project. Files and Git data stay on disk, and Manage locations… restores a removed project.

Remapping

Commands can be rebound in ~/.config/hocket/config.toml. A configured chord overrides the built-in global map:

1[keymap]
2"ctrl+shift+left" = "panel.move.right"
3"ctrl+shift+right" = "panel.move.left"
4"alt+x" = "panel.close"

Every command is also available by name from the ctrl+k command palette. Project discovery is available there as Find and add project… and Manage project locations…; clicking the Projects header or its + opens the same actions. Inside project discovery, Up/Down move, Right expands or enters, Left collapses or returns to a parent, Enter descends or adds a repository, ctrl-l changes the filesystem root, and Esc clears the query before backing out of scope.