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(alsocmd,commandormeta),ctrl(orcontrol),alt(oroption) andshift.superis the command key: Cmd on macOS, Ctrl elsewhere, so off macOSctrl+pandsuper+pare 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,f1tof20, or a key's code as floem names it, such asKeyHorNumpadEnter. 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 ofconfig.tomlthen.
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
| Action | Default | What it does |
|---|---|---|
new_work | super+n | Opens the new worktree form |
new_window | super+shift+n | Opens another window |
open | super+o | Opens a pull request or issue from its link or number |
settings | super+, | Opens Settings |
close | super+w | Closes Settings, the active file, the item, or the window, in that order |
back | none | Closes Settings or returns to the sidebar from an item or New Work |
history_back | super+[ | Goes back to where you were |
history_forward | super+] | Goes forward again after going back |
toggle_agents | super+shift+a | Shows or hides the list of agent runs |
send_feedback | none | Opens or closes Send Feedback |
Sidebar
| Action | Default | What it does |
|---|---|---|
toggle_sidebar | super+\ | Shows or hides the sidebar |
focus_search | super+shift+f, / | Opens the sidebar and focuses its search box |
inbox | ctrl+1 (macOS), alt+1 (other) | Shows the Inbox, opening the sidebar if needed |
worktrees | ctrl+2 (macOS), alt+2 (other) | Shows Worktrees, opening the sidebar if needed |
browse | ctrl+3 (macOS), alt+3 (other) | Shows Browse, opening the sidebar if needed |
next_item | j | Opens the next sidebar item, or the first if none is open. Skips browser-only notifications. |
previous_item | k | Opens the previous sidebar item |
mark_done | e | Marks the Inbox row under the pointer done, else the open item's row |
mark_unread | shift+u | Marks the Inbox row under the pointer unread, else the open item |
pin | p | Pins or unpins the row under the pointer, else the open one |
Item
| Action | Default | What it does |
|---|---|---|
show_conversation | super+1 | Shows the open item's Conversation |
show_code | super+2 | Shows the open item's Code |
next_tab | super+shift+] | Goes to the next file tab, Cmd-} on a US keyboard |
previous_tab | super+shift+[ | Goes to the file tab before, Cmd-{ |
refresh | super+r | Fetches the open item from GitHub again |
open_on_github | super+shift+o | Opens the row under the pointer, else the open item, in the browser |
copy_link | super+shift+c | Copies the open item's link |
copy_branch_name | none | Copies the open item's branch name |
start_work | none | Starts work on the open item |
toggle_review | super+shift+r | Opens or closes Review when available |
toggle_merge | super+shift+m | Opens or closes Merge when available |
Conversation & Code
| Action | Default | What it does |
|---|---|---|
comment | a | Comments on the selected lines on Code, or on the item as a whole on Conversation |
page_up | pageup | Scrolls up a page |
page_down | pagedown | Scrolls down a page |
scroll_to_top | super+up | Scrolls to the top |
scroll_to_end | super+down | Scrolls to the end |
Code
| Action | Default | What it does |
|---|---|---|
go_to_file | super+p | Opens Go to File. Press again to select the next result. |
toggle_files | super+/, super+shift+e | Shows or hides the file tree |
next_change | ] | Goes to the next change in the file |
previous_change | [ | Goes to the change before |
toggle_viewed | v | Marks the active file viewed or unviewed |
next_unviewed | shift+] | Goes to the next file not yet viewed |
previous_unviewed | shift+[ | Goes to the previous unviewed file |
toggle_wrap | none | Turns Word wrap on or off |
go_to_definition | f12 | Goes to where the symbol at the caret is defined |
go_to_type_definition | none | Goes to where the symbol's type is defined |
go_to_implementations | super+f12 | Lists what implements the symbol |
find_references | shift+f12 | Lists where the symbol is used |
call_hierarchy | alt+shift+h | Shows what calls the function, and what it calls |
Find
| Action | Default | What it does |
|---|---|---|
find | super+f | Opens the find bar on the code or Conversation |
find_next | super+g | Goes to the next match |
find_previous | super+shift+g | Goes to the match before |
find_match_case | alt+super+c | Turns match case on or off, while the bar is up |
find_whole_word | alt+super+w | Turns whole word on or off, while the bar is up |
find_regex | alt+super+r | Turns regular expressions on or off, while the bar is up |
Composer
| Action | Default | What it does |
|---|---|---|
bold | super+b | Makes the selection bold |
italic | super+i | Makes the selection italic |
code | super+e | Makes the selection code |
link | super+k | Makes the selection a link |
quote | super+shift+. | Quotes the selected lines |
numbered_list | super+shift+7 | Makes the selected lines a numbered list |
bullet_list | super+shift+8 | Makes the selected lines a list |
task_list | super+shift+l | Makes the selected lines a task list |
suggest | super+g | Adds a suggestion, in a comment on lines of code |
toggle_preview | super+shift+p | Switches between Write and Preview |