phux docs

Actions

Every action a key binding, palette row, context menu, or hook can dispatch, with its parameters.

An action is what a keybinding, palette row, context-menu entry, or hook binds to: a bare name, or a name plus parameters ({ action = "split-pane", direction = "vertical" } in config TOML). The table lists every action the TUI dispatcher handles, in the canonical ACTION_NAMES order; unit tests pin this inventory to the dispatcher and the command palette, so an action appears here exactly when the binary handles it.

The Palette column is the command-palette section the action is offered under; a dash means the palette deliberately has no row for it (reasons follow the table). An empty Parameters cell means the action takes none.

ActionPaletteParametersDescription
split-panePanedirection = horizontal | vertical; host? (satellite); resource? (@N or host/@N)Split the focused pane side-by-side (vertical divider)
move-panePanetarget (local Terminal id; picker-supplied)Move the focused pane beside another pane…
kill-panePaneKill the focused pane’s terminal
close-viewPaneHide the focused pane; its terminal keeps running
reopen-viewsTabShow hidden terminals, one tab each
new-windowTabcwd? (working directory on the attached server’s host)Open a new tab
go-to-directoryTabpath? (absolute, ~, or ~/...; bare starts at the focused pane’s directory)Browse directories on the attached server’s host and open a new tab in one
find-pathPanepath? (directory to browse; defaults to the focused pane’s directory)Browse or fuzzy-search host paths and insert a literal path into the focused pane
insert-pathPanepath (selected absolute path)Insert a selected host path without running the command
kill-windowTabterminals? (selectors the confirm committed; omitted opens the confirm)Kill the active tab’s terminals…
kill-sessionSessionid, name (optional pinned session; defaults to current)Confirm ending all session work, including resources added meanwhile, and delete it
delete-empty-sessionSessionid, name (optional pinned session; defaults to current)Confirm deletion of an empty session; never terminates members
organizeSessionPut every pane in the session it belongs in (phux organize); moves membership only
organize-sessionSessionMove this session’s panes to the sessions they belong in; other sessions stay
organize-undoSessionReverse the last organize run: panes move back, renames revert, created sessions go
session-actions—id, name, host (pinned picker identity)Open management for the selected session row
next-windowTabSwitch to the next tab
previous-windowTabSwitch to the previous tab
select-window—index (0-based tab position)Focus the tab at a given index
move-window—index (0-based destination) or delta (signed slots, e.g. -1); clamped to the endsMove the active tab to another position in the tab order
rename-windowTabname? (bare opens an interactive prompt)Rename the active tab (interactive prompt)
rename-sessionSessionname? (bare opens an interactive prompt)Rename the current session (interactive prompt)
focus-directionPanedirection = left | right | up | downMove focus to the pane on the left
resize-panePanedirection = left | right | up | down; amount (cells)Grow the focused pane to the left
show-help—Open the fuzzy commands and help finder
getting-startedphuxGetting started: detach, return, the Agents list, and command discovery
copy-mode—Enter copy-mode on the focused pane (scrollback navigation, search, selection, yank)
detachphuxDetach this client from the session
next-panePaneCycle focus to the next pane
previous-panePaneCycle focus to the previous pane
last-panePaneJump back to the previously focused pane
toggle-zoomPaneZoom the focused pane to fill the tab (toggle)
toggle-sidebarphuxShow or hide the sidebar (toggle)
command-palette—Open the fuzzy commands and help finder
context-menuPaneOpen the context menu for the focused pane
window-pickerTabPick a tab from all sessions (grouped)
session-pickerSessionBrowse sessions and live host availability
agent-fleetphuxEvery agent, its state, and whether it needs you
agents-filterphuxscope (all, session, attention, or next), host (all, here, a satellite name, or next); both optionalNarrow the sidebar’s Agents panel: every agent, this session’s, or the ones that need you, on one machine or all of them. Bare, steps to the next scope
focus-pane—window (window index), pane (DFS leaf ordinal)Focus a pane by window index and DFS leaf ordinal
next-attentionPaneJump to the next pane waiting for an answer
return-from-attentionPaneReturn to where attention navigation started
switch-session—name; window? (window index to select after the switch); pane? (DFS leaf ordinal to focus in that window); host? (a satellite of this hub: opens that session’s active pane here through the relay instead of re-attaching)Re-attach this client to another session
switch-host—host (a registered host name, or local for this machine); name (the session there)Re-attach this terminal to a session on another machine
toggle-project-group—project (the group’s key, as the sidebar header carries it)Collapse or expand one project group in the sidebar’s Sessions zone
new-sessionSessionname? (bare opens an interactive prompt); cwd?; host?Create a new session and switch to it
last-sessionSessionSwitch back to the previous session
next-sessionSessionSwitch to the next session by name
previous-sessionSessionSwitch to the previous session by name
take-inputPaneTake the wheel: seize exclusive input over the focused pane
give-inputPaneGive back the wheel: release the focused pane’s input lease
signal-terminalPanesignal = interrupt | freeze | resume | terminate | killSignal the focused pane’s process group (freeze, resume, kill)
set-panePanemouse = on | off | toggleToggle mouse capture for the focused pane
plugin-action—plugin (the plugin’s id), id (the manifest action’s id)Run an enabled plugin’s manifest action
plugin-pane—plugin, paneOpen an enabled plugin’s manifest pane
reload-configphuxReload the config file (keybindings, theme, status bar)
settingsphuxSettings: browse, search, and edit every option in place
report-bugphuxnote? (optional free-text description)Write a local bug report (session, logs, screen) and copy its path
rec-markphuxlabel? (bare chord writes an empty marker)Drop an asciicast marker into the recording in progress
enter-mode—name (a [keybindings.modes.<name>] table); once? (true leaves after one of the mode’s keys)Turn on a key mode: its keys work without the prefix until exit-mode or Esc
exit-mode—Leave the active key mode

Why the dash rows have no palette entry:

  • command-palette — it is an entry alias for the finder, so listing it inside the finder would recurse.
  • show-help — it is an entry alias for the same finder as command-palette, so listing it would duplicate that surface.
  • select-window — parameterized by index, which the palette has no UI to collect; the tab picker is the surface for “jump to tab N”.
  • move-window — parameterized by direction; bound to < and > under the leader, offered in the tab context menu, and done by dragging a tab or a sidebar tab row.
  • session-actions — opened by Tab in the session picker or right-click on a sidebar session.
  • switch-session — requires a name arg supplied by the session picker (or the fleet’s foreign rows), so a bare palette row would have no target to act on.
  • switch-host — requires host and name args supplied by the sidebar’s machine segments or the session picker’s machine groups, so a bare palette row would have no target to act on.
  • toggle-project-group — requires the project arg the sidebar’s group header supplies, so a bare palette row would have no group to act on.
  • copy-mode — a modal input surface entered from its keybinding, not a one-shot command the palette can commit.
  • plugin-action — its palette rows are built dynamically from enabled plugins’ manifests, one per manifest action, carrying plugin/id args a static row could not supply.
  • plugin-pane — same shape as plugin-action: dynamic rows from enabled plugins’ manifest [[panes]], carrying plugin/pane args.
  • focus-pane — parameterized by coordinates only the agent-fleet dashboard’s rows can supply (the select-window precedent).
  • enter-mode — parameterized by name, a mode the config defines; reached from its binding (the shipped resize mode is the prefix then R).
  • exit-mode — only meaningful inside a key mode, where its own key (or Esc) reaches it.