Add support for cmd+ keybinds on macOS

Summary

Currently, opencode only supports ctrl+, alt+, and shift+ key combinations in keybinds. On macOS, users expect to use the Command key (cmd+) for shortcuts, but this is not currently supported.

Current Behavior

Keybinds like "cmd+p" in config are ignored/don't work
Only ctrl+, alt+, and shift+ combinations work
This forces Mac users to use ctrl+ which is a different physical key than the expected Command key

Expected Behavior

cmd+ keybinds should work on macOS (e.g., "cmd+p", "cmd+n")
This would match standard macOS conventions where Command key is used for shortcuts

Technical Details

The issue appears to be in the TUI's key handling (Bubble Tea v2), where the Keybinding.Matches function compares key strings with msg.String(). The current codebase only shows examples of ctrl+, alt+, and shift+ combinations.

Use Case

Mac users naturally expect cmd+p to work for navigation shortcuts, similar to how cmd+c works for copy in other Mac applications.

just spent more time than i care to admit unmapping/remapping iterm2 user and global keybinds, setting/unsetting macOS system keyboard shortcuts, trial & erroring various keybinds in opencode.json, trying to figure out why some mappings work fine, but others simply didn't. i'd absolutely love the command palette to be cmd+shift+p for muscle memory, but there was nothing i could do to call the command palette. low and behold "app_help": "ctrl+p", triggers just fine. not exactly what i want, but at least it works.

I'd been looking through the keybinds page examples, and where there are many.. but it was not obvious that Apple's command key (and possibly the Super/Windows key as well?) could not be used. If there are unusable keys, it'd be hugely helpful to specify what is compatible and what isn't, in the docs. I'm new to this project, but if you accept PRs for documentation, i'm willing to add some more details with a couple more examples, now that i know exactly what's going on.

we accept prs for most things, we are about to ship a rewrite of the tui so some of what u learned may change

@rekram1-node

thanks for the heads up, i really do appreciate it!

edit: @rekram1-node would you mind linking the relevant tui change in here? i'd like to see what direction this is headed.

@scottrbaxter

@scottrbaxter does this work? https://github.com/sst/opencode/blob/opentui/CHANGES.md

summary of the changes, and opentui is the branch w/ them

@rekram1-node

@rekram1-node unfortunately, going from 0.15.29 to 1.0.15 last night, there are so many new issues that i honestly can't even test this in any meaningful way yet. really unfortunate, and i'm trying to find a happy medium, but this >1.0 change has been very challenging. i'm now subscribed to several github issues, in hopes to see restored features that were lost, just a few days ago. for now, i'm trying to find the easiest way to pin and stay on an older release, while setting up a local test container just to trial/error use cases in a non-destructive way. today, i have way too much work to do to spend considerable time on this... the goods and bads of rapid development. this project's changes just move so fast right now. can't wait until it stabilizes... this will be a game changer, for sure.

new bug example: on 0.15.29 i was able to simply type q <enter> and opencode would quit... like a quick(er) way to /q. this was incredibly convenient. i've now accidentally sent q to a model more times than i can count. muscle memory is hard.

honestly, i'd love to see it smart enough to accept single character commands, like q to quit, e to open editor, s to list sessions, etc. alongside slash commands. i could see that being incredibly valuable, and not intrusive in any meaningful way.

coming back full circle, i really really wish there was support for Apple's command key as well... effectively aligning configuration with vim mappings, which is what i expected the first time i saw the <leader> reference in opencode's keybinds doc. e.g.

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
...

Unless I'm missing something, one can use super+<key>, which maps to cmd on macOS.

The only unfortunate thing is that the TUI then also shows super+<key>, which is confusing on macOS as the command is the super key. But that's a minor issue.

Might be good to add a more obvious blurb in the docs calling out that super is supported? I can imagine many macOS users would prefer to use cmd+ rather than ctrl+, and the docs don't make it super obvious that it's available (super is buried amongst a bunch of other commands)

Yeah 100% I only guessed it was supported after seeing that the UI is rendered with web tech where super refers to macOS's cmd

Unless I'm missing something, one can use super+<key>, which maps to cmd on macOS.

The only unfortunate thing is that the TUI then also shows super+<key>, which is confusing on macOS as the command is the super key. But that's a minor issue.

I want to change it on my Mac so that cmd+v pastes the image from the clipboard (currently the default is ctrl+v), but using super+v doesn’t work. Do you have any information about this?

I found a temporary workaround, for folks on MacOS using iTerm2

First, in ~/.config/opencode/opencode.json (or wherever your json is), add these 2 to your keybinds:

  "keybinds": {
    ...
    "input_newline": "enter",
    "input_submit": "alt+enter"
  }

Next, you can get iTerm to remap the CMD+Enter keys to ALT+Enter (which is Option+Enter in macOS)

This does nothing outside opencode, but within it you get a sourcegraph/amp like experience :))

Note: unfortunately this doesn't work for pasting images too, otherwise you'll break the text-paste version

@flekschas

@flekschas

The only unfortunate thing is that the TUI then also shows super+, which is confusing on macOS as the command is the super key. But that's a minor issue.

#23853 shows "cmd" on TUI on macOS

@KevinWu098

can imagine many macOS users would prefer to use cmd+ rather than ctrl+

#23854 changes cmd <-> ctrl for default(not user config) keybinding on macOS.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

Add support for cmd+ keybinds on macOS #653

Summary

Current Behavior

Expected Behavior

Technical Details

Use Case

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add support for cmd+ keybinds on macOS #653

Description

Summary

Current Behavior

Expected Behavior

Technical Details

Use Case

Activity

scottrbaxter commented on Oct 29, 2025

rekram1-node commented on Oct 29, 2025

scottrbaxter commented on Oct 30, 2025

rekram1-node commented on Oct 30, 2025

scottrbaxter commented on Nov 3, 2025

flekschas commented on Jan 15, 2026

KevinWu098 commented on Jan 24, 2026

flekschas commented on Jan 25, 2026

FischLu commented on Jan 28, 2026

scottsus commented on Mar 5, 2026

jjangga0214 commented on Apr 22, 2026

github-actions commented on Jun 22, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions