OpenCode Hotkeys — Desktop Keybinds, Keymap and Install Guide

Desktop surface

One keymap. Two surfaces.

OpenCode Desktop gets the browser layer. The terminal edition keeps the full Hotkey Studio. The install and the mental model stay separate, so neither one pretends to be the other.

Tabs that act like tabs

Alt+Enter opens a draft. Alt+1…9 jumps straight to an open tab. Alt+PageUp/Down cycles without a trip to the tab strip.

Built for real layouts

Persian and Arabic layouts change what letter keys produce. The primary bindings use digits, navigation keys, and punctuation, so they keep working.

A settings change, not a patch

The installer merges native command ids into OpenCode's own settings, writes a backup, and gives you a one-command undo.

New in 1.0 · Doctor

--doctor reports installed, missing, customized, and duplicate bindings. Add --json when you want machine-readable output.

Backups you control

List them with --backups, restore one by name, or keep the newest --prune N and delete the rest.

Safer installs

--diff previews old and new bindings without writing. --keep-custom leaves the keys you edited yourself untouched.

The keymap

Every desktop shortcut, in one place.

Install these as a set, or pick the ones you want from Settings → Shortcuts. The Latin-letter and native OpenCode defaults are kept as additional bindings.

Desktop keyboard shortcuts for OpenCode
Action	Primary	Also works
New tab	`Alt`+`Enter`	`Alt`+`T`·`Mod`+`T`·`Mod`+`N`
Switch to tab 1…9	`Alt`+`1…9`	`Mod`+`1…9`
Previous tab	`Alt`+`PageUp`	`Alt`+`Home`·`Ctrl`+`Shift`+`Tab`
Next tab	`Alt`+`PageDown`	`Alt`+`End`·`Ctrl`+`Tab`
Search files, commands, sessions	`Alt`+`/`	`Alt`+`O`·`Mod`+`P`
Open Settings	`Alt`+`.`	`Alt`+`K`·`Mod`+`,`
Close current tab	`Mod`+`W`	Native default
Reopen closed tab	`Mod`+`Shift`+`T`	Native default
Previous / next session	`Alt`+`↑`/`↓`	Native default

Alt+1…9 switches open tabs, not history. Everything runs while the app is focused. Mod is Ctrl on Linux and Windows, and Cmd on macOS. On macOS, prefer the Cmd alternatives.

Tabs, not history.

Alt+1…9 moves between tabs that are already open. To reach any session, use Alt+/ and choose it from the search palette.

Why two sets of keys?

The desktop matcher compares the character a key produces, not its physical position. On a Persian layout, Alt+T produces a Persian character, so the primary set uses digits, arrows, and punctuation.

macOS uses Cmd.

Option+letter and Option+digit can insert special characters on macOS. Use Cmd+1…9, Cmd+T, Cmd+P, and Cmd+, instead; the installer writes both sets.

Install

One command. A clean undo.

The installer uses Node's standard library only. It finds the desktop settings file, backs it up, and merges 14 keybinds without touching anything else.

Run the installer

Use the one-liner or clone the repository. There is no npm install step.
Quit and reopen the app

OpenCode Desktop reads its keybinds at startup. The installer never closes the app for you.
Press Alt+Enter

You should get a new draft tab. Use Alt+1…9 to move between open tabs.

terminal

$ curl -fsSL https://raw.githubusercontent.com/NarimanKhaleghi/opencode-hotkeys/main/install-desktop.sh | sh

PS> irm https://raw.githubusercontent.com/NarimanKhaleghi/opencode-hotkeys/main/install-desktop.ps1 -OutFile "$env:TEMP\opencode-hotkeys.ps1"
PS> powershell -ExecutionPolicy Bypass -File "$env:TEMP\opencode-hotkeys.ps1"

Node 20+ OpenCode Desktop 1.19+

Installer reference, manual setup, and undo

The installer writes the app's own settings file. Quit the app before uninstalling on Windows. Every write creates a timestamped backup.

--check

Exit 0 only when every managed binding is installed.

--print

Print the managed keybind JSON.

--dry-run

Show changes without writing.

--diff

Show current and new bindings without writing.

--doctor

Report missing, customized, and duplicate bindings.

--backups

List timestamped backups.

--prune N

Keep the newest N backups.

--uninstall

Remove only unmodified managed bindings.

--restore latest

Restore the newest backup next to default.dat.

For a manual file edit, parse the JSON string stored at settings.v3 and merge these entries into its keybinds object:

{
  "tab.new": "alt+enter,alt+t,mod+t,mod+n",
  "tab.1": "alt+1,mod+1",
  "tab.2": "alt+2,mod+2",
  "tab.3": "alt+3,mod+3",
  "tab.4": "alt+4,mod+4",
  "tab.5": "alt+5,mod+5",
  "tab.6": "alt+6,mod+6",
  "tab.7": "alt+7,mod+7",
  "tab.8": "alt+8,mod+8",
  "tab.9": "alt+9,mod+9",
  "tab.prev": "alt+pageup,alt+home,mod+option+arrowleft,ctrl+shift+tab",
  "tab.next": "alt+pagedown,alt+end,mod+option+arrowright,ctrl+tab",
  "file.open": "alt+/,alt+o,mod+p",
  "settings.open": "alt+.,alt+k,mod+comma"
}

On Linux and macOS, mod means Ctrl. On macOS it means Cmd. The desktop app accepts comma-separated alternatives for one action.

Under the hood

A small, reversible pipeline.

No injection, no wrapper, no service. The installer reads the same settings file the app uses and writes it back atomically.

01
Find the file

Checks the standard Linux, macOS, and Windows paths, plus OPENCODE_DESKTOP_CONFIG.
02
Parse settings.v3

The app stores a JSON string inside default.dat. Only its keybinds object is touched.
03
Merge 14 keys

Existing bindings, including your own, stay in place. Managed entries are replaced.
04
Back up, then write

A timestamped backup is created before an atomic rename. Undo is one command.

Linux: ~/.config/ai.opencode.desktop/default.dat macOS: ~/Library/Application Support/ai.opencode.desktop/default.dat Windows: %APPDATA%\ai.opencode.desktop\default.dat

Limits

What this is not.

The desktop layer is deliberately narrow. Knowing the edges makes the shortcuts easier to trust.

Not an OS-wide hotkey daemon

Shortcuts work while OpenCode Desktop is focused. There is no global listener or background process.

No Studio on the desktop

The desktop app does not load TUI plugins. Hotkey Studio stays in the terminal edition; the desktop uses native Settings → Shortcuts.

Tab slots, not session history

Alt+1…9 only reaches tabs that are open. Alt+/ searches the full session list and is the better everyday jump.

Upstream can rename commands

The bindings target built-in command ids. A future app update can change one; run --check after updating and reinstall if needed.

Terminal edition

The TUI still has the Studio.

For preset switching, quick session slots, and a full rebinding UI, use the terminal edition. It is a separate plugin with its own install.

Native, browser, and notes presets.
Quick slots with pinned and recent sessions.
Hotkey Studio with capture, conflicts, and reset.

Open the TUI guide

Hotkey Studio in the OpenCode terminal UI — Hotkey Studio · terminal edition

Questions

Before you install.

Short answers about layout, undo, updates, and what the desktop app can and cannot load.

Why do only Alt+1…9 work on my keyboard?

Your layout is producing non-Latin characters for letter keys. Use Alt+Enter, Alt+PageUp/Down, Alt+/, and Alt+. — the installer leads with those stable keys. Alt+T, Alt+O, and Alt+K remain for Latin layouts.

Does it work on macOS and Windows?

Yes. The installer detects all three platforms and writes both Alt and Cmd/Mod bindings. On macOS, Option+letter may type special characters, so the reliable set is Cmd+1…9, Cmd+T, Cmd+P, and Cmd+,. On Windows, quit OpenCode Desktop before installing so the settings file is not locked.

Does this patch or wrap OpenCode Desktop?

No. It only edits the app's own keybind settings. There is no fork, no injected script, and no background process.

How do I undo the install?

Run desktop/install.mjs --uninstall, or restore the newest backup with --restore latest. The installer prints the backup path after every write.

Do I need npm?

No. The desktop installer has no npm dependencies. You need Node.js 20+ to run it, or you can edit the app's shortcuts from the native Settings window.

Will an OpenCode update erase it?

Your settings file survives app updates. A future release can rename a built-in command, so run --check after a major update and reinstall if a binding is reported missing.

Does it work when the app is in the background?

No. These are app shortcuts, not global hotkeys. The OpenCode Desktop window must be focused.

Stop reaching for the mouse.