Perch
Guide contents

Field guidePreferences and shortcuts

Keyboard shortcuts

Look up a shortcut by action, assign a different key, or remove a binding.

Customizing keybindings

Open Settings → Keyboard shortcuts to change a shortcut. To assign several keys to one action, edit [keybindings] in config.toml. Use the action ID from the tables below. A string assigns one key, a list assigns several, and "" or [] clears them. Your assignment replaces all defaults for that action.

[keybindings]
go_to_file = "super+t"          # Go to File on Cmd-T, and no longer on Cmd-P
pin = ""                        # no key; [] does the same
refresh = ["super+r", "f5"]     # two keys for one action
toggle_sidebar = 'super+\'     # a backslash in single quotes, or "super+\\"

Join the modifiers and the key with +. Capitalization doesn’t matter.

  • Modifiers: super (also cmd, command or meta), ctrl (or control), alt (or option) and shift. super is the command key: Cmd on macOS, Ctrl elsewhere, so off macOS ctrl+p and super+p are the same key.
  • Keys: a letter, a digit, punctuation as a US keyboard has it ([ ] \ / , . ; ' = - `), enter, escape, tab, space, backspace, delete, up, down, left, right, pageup, pagedown, home, end, f1 to f20, or a key's code as floem names it, such as KeyH or NumpadEnter. Keys are physical: shift+] is the key a US keyboard writes } with, wherever your layout puts it.
  • A backslash is an escape in a TOML string in double quotes, so write super+\ as "super+\\", or as 'super+\' in single quotes. "super+\" leaves the string open, and Perch can't read any of config.toml then.

Modifiers must match exactly. For example, super+g does not match Cmd-Shift-G. Perch reports unknown action IDs or invalid keys and applies the other entries.

A printable shortcut without Cmd, Ctrl, or Alt works only outside text fields. For example, / focuses sidebar search while reading a PR, but types a slash when you’re writing a comment.

Settings flags shortcuts that compete in the same place. Some can share a key. For example, super+g adds a suggestion while composing a line comment and finds the next match in the editor. Window actions such as New Work, Close, Go to File, and Toggle Files also work inside a message box and take priority there.

Menus and tooltips show the first shortcut assigned to an action. On macOS, the application menu displays the first shortcut for New Window, Open…, and Settings… unless it’s a plain typing key. Additional bindings still work in the window.

These stay as they are: Escape, Enter, the arrows and Tab inside menus, Go to File, pickers, dialogs and the find bar; the text keys of boxes and the editor, Cmd-C, Cmd-A and the like; Cmd-Enter, which sends or submits; Cmd-click on a symbol; the mouse's back and forward buttons; the single letters of an open item menu; and the keys macOS keeps, Cmd-Q, Cmd-H, Cmd-Opt-H, Cmd-M, Cmd-` and Cmd-Tab. Settings won't take these macOS keys for an action. An action given Cmd-Q, Cmd-H, Cmd-Opt-H or Cmd-Tab by hand never runs, as macOS has them first, and Settings says so on its row.

In Settings, click an action’s shortcut (or focus it and press Enter or Space), then press the new key. Escape cancels. Click × to clear all bindings for that action or the reset arrow to restore its defaults. Use the configuration file if you want several bindings for one action.

Hold Command on macOS or Ctrl on Linux to see shortcuts on the sidebar and view tabs and on toolbar buttons. Narrow toolbars hide hints when space is tight. Custom shortcuts take priority over the default Inbox, Worktrees, and Browse keys.

Default shortcuts by view

The tables use the same groups and action IDs as Settings.

General

ActionDefaultWhat it does
new_worksuper+nOpens the new worktree form
new_windowsuper+shift+nOpens another window
opensuper+oOpens a pull request or issue from its link or number
settingssuper+,Opens Settings
closesuper+wCloses Settings, the active file, the item, or the window, in that order
backnoneCloses Settings or returns to the sidebar from an item or New Work
history_backsuper+[Goes back to where you were
history_forwardsuper+]Goes forward again after going back
toggle_agentssuper+shift+aShows or hides the list of agent runs
send_feedbacknoneOpens or closes Send Feedback
ActionDefaultWhat it does
toggle_sidebarsuper+\Shows or hides the sidebar
focus_searchsuper+shift+f, /Opens the sidebar and focuses its search box
inboxctrl+1 (macOS), alt+1 (other)Shows the Inbox, opening the sidebar if needed
worktreesctrl+2 (macOS), alt+2 (other)Shows Worktrees, opening the sidebar if needed
browsectrl+3 (macOS), alt+3 (other)Shows Browse, opening the sidebar if needed
next_itemjOpens the next sidebar item, or the first if none is open. Skips browser-only notifications.
previous_itemkOpens the previous sidebar item
mark_doneeMarks the Inbox row under the pointer done, else the open item's row
mark_unreadshift+uMarks the Inbox row under the pointer unread, else the open item
pinpPins or unpins the row under the pointer, else the open one

Item

ActionDefaultWhat it does
show_conversationsuper+1Shows the open item's Conversation
show_codesuper+2Shows the open item's Code
next_tabsuper+shift+]Goes to the next file tab, Cmd-} on a US keyboard
previous_tabsuper+shift+[Goes to the file tab before, Cmd-{
refreshsuper+rFetches the open item from GitHub again
open_on_githubsuper+shift+oOpens the row under the pointer, else the open item, in the browser
copy_linksuper+shift+cCopies the open item's link
copy_branch_namenoneCopies the open item's branch name
start_worknoneStarts work on the open item
toggle_reviewsuper+shift+rOpens or closes Review when available
toggle_mergesuper+shift+mOpens or closes Merge when available

Conversation & Code

ActionDefaultWhat it does
commentaComments on the selected lines on Code, or on the item as a whole on Conversation
page_uppageupScrolls up a page
page_downpagedownScrolls down a page
scroll_to_topsuper+upScrolls to the top
scroll_to_endsuper+downScrolls to the end

Code

ActionDefaultWhat it does
go_to_filesuper+pOpens Go to File. Press again to select the next result.
toggle_filessuper+/, super+shift+eShows or hides the file tree
next_change]Goes to the next change in the file
previous_change[Goes to the change before
toggle_viewedvMarks the active file viewed or unviewed
next_unviewedshift+]Goes to the next file not yet viewed
previous_unviewedshift+[Goes to the previous unviewed file
toggle_wrapnoneTurns Word wrap on or off
go_to_definitionf12Goes to where the symbol at the caret is defined
go_to_type_definitionnoneGoes to where the symbol's type is defined
go_to_implementationssuper+f12Lists what implements the symbol
find_referencesshift+f12Lists where the symbol is used
call_hierarchyalt+shift+hShows what calls the function, and what it calls

Find

ActionDefaultWhat it does
findsuper+fOpens the find bar on the code or Conversation
find_nextsuper+gGoes to the next match
find_previoussuper+shift+gGoes to the match before
find_match_casealt+super+cTurns match case on or off, while the bar is up
find_whole_wordalt+super+wTurns whole word on or off, while the bar is up
find_regexalt+super+rTurns regular expressions on or off, while the bar is up

Composer

ActionDefaultWhat it does
boldsuper+bMakes the selection bold
italicsuper+iMakes the selection italic
codesuper+eMakes the selection code
linksuper+kMakes the selection a link
quotesuper+shift+.Quotes the selected lines
numbered_listsuper+shift+7Makes the selected lines a numbered list
bullet_listsuper+shift+8Makes the selected lines a list
task_listsuper+shift+lMakes the selected lines a task list
suggestsuper+gAdds a suggestion, in a comment on lines of code
toggle_previewsuper+shift+pSwitches between Write and Preview