Keymaps

Hardware keyboard shortcuts and the on-screen key bar for sophonz ADE — the built-in keymaps, the agent keys, the file format, and how to bring your own.

A keymap is a JSON file that binds hardware key combinations — cmd+t, ctrl+b then c, and so on — to app actions: new window, next pane, open Compose. Any key a keymap doesn't claim still reaches the terminal unchanged, so a keymap only ever adds shortcuts, never takes typing away. iOS and Android read the same file format, keymap v1, so one you export from a phone works on the other.

The same file can also describe the on-screen key bar: which rows it has, which keys are on them and what each one sends (The key bar). A file without that part keeps the app's built-in key bar.

The app ships with three built-in keymaps, read-only, and you can import as many of your own as you like.

The three templates

Import and export

Settings → Keys and input → Hardware keyboard → Keymap lists the built-in three plus any you've added, and shows which one is active.

• Export writes a .sophonz-keymap.json file for the current keymap, so you can back it up or hand it to the other device.
• Import reads a .sophonz-keymap.json file back in, key bar included. It's validated on the way in — a bad file is rejected with a reason and nothing changes — and, once it passes, added to the list and available to switch to.

The three built-in keymaps can't be edited or removed; anything you import is yours to change or delete.

The file format

{
  "$schema": "https://www.sophonz.io/schemas/keymap-v1.json",
  "format": "sophonz-keymap",
  "version": 1,
  "name": "My keys",
  "platform": "any",
  "options": { "optionAsMeta": true, "tmuxPrefix": { "enabled": false, "key": "ctrl+b" } },
  "bindings": [
    { "action": "window.new", "keys": "cmd+t" },
    { "action": "compose.send", "keys": "cmd+enter", "when": "compose" }
  ],
  "prefixBindings": [ { "action": "window.new", "key": "c" } ]
}

No properties beyond these are allowed, on the top-level object or on any binding.

Keys

Keys are written mod+mod+key, lower case:

• Modifiers, in this order, each at most once: cmd, ctrl, opt (alt also works and is read as opt), shift. cmd is Meta on Android.
• The key is one of a–z, 0–9, f1–f12, a named key — enter, esc, tab, space, backspace, delete, up, down, left, right, home, end, pageup, pagedown — or one of [ ] , . / ; ' \ - = `.
• Shift is still a modifier, not part of the key: tmux's % is shift+5, " is shift+', + is shift+= on a US layout.

Plain ctrl+letter, esc and tab are warned about if you bind them — the terminal wants those — and the templates never claim them. ctrl+space, 🌐 and Caps Lock are the system's own 한/영 switch and can never be bound; see below.

when

Every binding fires in one of two contexts:

• terminal (the default) — the terminal has focus.
• compose — the Compose sheet is open. Required for compose.send, compose.close and compose.mic, and not allowed on any other action.

prefixBindings have no when; they only make sense in the terminal, with the prefix already held.

Actions

The agent.* actions send what the agent in the current pane reads for that job, so one binding works for Claude Code, Codex and Gemini CLI alike. An app from before they existed refuses a file that uses them.

compose.send, compose.close and compose.mic can't be prefixBindings — they only exist inside Compose, and the prefix only fires in the terminal.

Limits and validation

A bad file changes nothing: the whole file is rejected, and every problem is listed with its JSON path, e.g. bindings[3].keys: "cmd+tt" is not a key. Checked, in the schema and again by each app:

• Valid JSON, an object, with format and version exactly right.
• No unknown property, action or key, and no when the action doesn't allow.
• name 1–40 characters.
• No two bindings claim the same keys under the same when; no two prefixBindings claim the same key.
• At most 200 bindings and 100 prefixBindings.
• The file itself is at most 64 KB.
• In a keyBar: row ids are unique, every key has exactly one of send, text, char, action, toggle, and every toggle key has a row to show and hide.

The key bar

The key bar's rows come from the active keymap. Settings → Keys and input → Key bar → Layout edits it: start from a preset, drag rows and keys into another order, hide or delete them, add your own, and change what any key sends. A built-in keymap is copied first. Hold any key on the bar to see what it sends — ⇧tab — Shift+Tab · Claude Code: switch permission mode — without pressing it; arrows and the other keys that repeat show it while they repeat, and the mic, which you hold to talk, has none.

On Android the extras sit right under the first row and the multiplexer row at the bottom, as they always have.

The agent keys

The agent row follows the agent st sees in the current pane — Claude Code, Codex or Gemini CLI — and shows nothing extra when there is none. The key at its front (codex ▾) or Settings → Keys and input → Key bar → Agent keys fixes it to one agent instead; Agent row sets whether it shows only while an agent runs, always, or never.

With no agent the row has esc esc, ⇧tab, ⇧← ⇧→, 1 2 3 and ⌥⏎ (Alt+Enter). There is no Shift+Enter key; ^J does the same job.

keyBar

"keyBar": { "groups": [
  { "id": "main", "layout": "fit", "keys": [
    { "toggle": "mux" }, { "action": "mod.ctrl", "label": "ctrl" }, { "send": "left", "repeat": true } ] },
  { "id": "codex", "title": "Codex", "when": "agent:codex", "toggle": "agent", "keys": [
    { "action": "agent.pick" },
    { "label": "⇧←", "send": "shift+left", "hint": { "en": "Codex: answer its questions", "ko": "Codex: 질문에 답하기" } },
    { "label": "esc esc", "text": ["\u001b", "\u001b"] } ] }
] }

Keys for a multiplexer action the machine does not support are left out, as are toggles for rows that do not apply.

Editors validate it too

The $schema line at the top of the file points at keymap-v1.json, a JSON Schema (2020-12). VS Code and most editors with JSON Schema support read it automatically: red squiggles on a bad key or an unknown action, and autocomplete for both, right in the editor — before you ever import the file.

The 한/영 switch

Ctrl+Space, 🌐 (or the equivalent key) and Caps Lock are the system's own input-source switch on iOS; Ctrl+Space, Shift+Space or the 한/영 key do the same on Android. The app never intercepts any of them — they reach the system exactly as if the app weren't there, so switching between English and Hangul while typing always works.

The switchers

switcher.windows (⌥⇥ by default) and switcher.sessions (⌥` by default) hold their modifiers: the key itself opens the switcher, each further tap while the modifier is down moves the selection (backwards with Shift added), and releasing the modifiers switches to what's selected. Esc cancels.