Example Config

A complete annotated config demonstrating profiles, modes, sequences, custom menus, aliases, shared modes, hold actions, and axis mappings.

{
  "trigger_threshold": 0.5,
  "debug_overlay": false,
  "hud_zoom": 1.0,
  "menu_style": "list",
  "aliases": {
    "tmux_leader": { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] }
  },
  "shared_modes": {
    "media": {
      "LB":         { "type": "keystroke", "key": "play_pause" },
      "RB":         { "type": "keystroke", "key": "next_track" },
      "dpad_up":    { "type": "keystroke", "key": "volume_up" },
      "dpad_down":  { "type": "keystroke", "key": "volume_down" }
    }
  },
  "global": {
    "left_stick":  { "type": "mouse_move", "speed": 15, "modifier": "RB", "modifier_speed": 3 },
    "right_stick": { "type": "scroll", "speed": 3, "y_inverted": true },
    "L3":          { "type": "left_click", "hold": { "type": "left_click_hold" } },
    "R3":          { "type": "right_click" }
  },
  "profiles": {
    "default": {
      "apps": [],
      "default_mode": "general",
      "global": {
        "options": { "type": "mode_select" }
      },
      "modes": {
        "general": {
          "A":          { "type": "keystroke", "key": "space" },
          "B":          { "type": "keystroke", "key": "escape" },
          "dpad_up":    { "type": "keystroke", "key": "up" },
          "dpad_down":  { "type": "keystroke", "key": "down" },
          "dpad_left":  { "type": "keystroke", "key": "left" },
          "dpad_right": { "type": "keystroke", "key": "right" }
        }
      }
    },
    "terminal": {
      "apps": ["com.mitchellh.ghostty", "com.apple.Terminal", "com.googlecode.iterm2"],
      "default_mode": "shell",
      "global": {
        "options": { "type": "mode_select" },
        "LB":      { "type": "prev_mode" },
        "RB":      { "type": "next_mode" }
      },
      "context_modes": {
        "claude": "agent",
        "nvim":   "nvim",
        "zsh":    "shell",
        "ssh":    "shell"
      },
      "hidden_modes": ["agent"],
      "modes": {
        "agent": {
          "A":          { "type": "keystroke", "key": "return" },
          "B":          { "type": "keystroke", "key": "escape" },
          "X":          { "type": "keystroke", "key": "`continue`" },
          "dpad_up":    { "type": "keystroke", "key": "up" },
          "dpad_down":  { "type": "keystroke", "key": "down" }
        },
        "shell": {
          "A":          { "type": "keystroke", "key": "return" },
          "B":          { "type": "keystroke", "key": "c", "modifiers": ["ctrl"] },
          "X":          { "type": "keystroke", "key": "l", "modifiers": ["ctrl"] },
          "Y":          { "type": "menu", "name": "git" },
          "dpad_up":    { "type": "keystroke", "key": "up" },
          "dpad_down":  { "type": "keystroke", "key": "down" },
          "dpad_left":  { "type": "keystroke", "key": "left" },
          "dpad_right": { "type": "keystroke", "key": "right" }
        },
        "nvim": {
          "A":            { "type": "keystroke", "key": "return" },
          "B":            { "type": "keystroke", "key": "escape" },
          "X":            { "type": "keystroke", "key": "u" },
          "Y":            { "type": "keystroke", "key": "r", "modifiers": ["ctrl"] },
          "dpad_up":      { "type": "keystroke", "key": "k" },
          "dpad_down":    { "type": "keystroke", "key": "j" },
          "dpad_left":    { "type": "keystroke", "key": "h" },
          "dpad_right":   { "type": "keystroke", "key": "l" },
          "X+dpad_up":    { "type": "keystroke", "key": "k", "modifiers": ["ctrl"] },
          "X+dpad_down":  { "type": "keystroke", "key": "j", "modifiers": ["ctrl"] }
        },
        "tmux": {
          "A": {
            "type": "sequence",
            "steps": [
              { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] },
              { "type": "keystroke", "key": "return" }
            ],
            "delay": 0.05
          },
          "dpad_up": {
            "type": "sequence",
            "steps": [
              { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] },
              { "type": "keystroke", "key": "up" }
            ]
          },
          "dpad_down": {
            "type": "sequence",
            "steps": [
              { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] },
              { "type": "keystroke", "key": "down" }
            ]
          },
          "dpad_left": {
            "type": "sequence",
            "steps": [
              { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] },
              { "type": "keystroke", "key": "left" }
            ]
          },
          "dpad_right": {
            "type": "sequence",
            "steps": [
              { "type": "keystroke", "key": "a", "modifiers": ["ctrl"] },
              { "type": "keystroke", "key": "right" }
            ]
          }
        }
      }
    }
  },
  "menus": {
    "git": [
      { "label": "git status",    "action": { "type": "keystroke", "key": "`git status\n`" } },
      { "label": "git diff",      "action": { "type": "keystroke", "key": "`git diff\n`" } },
      { "label": "git log",       "action": { "type": "keystroke", "key": "`git log --oneline -20\n`" } },
      { "label": "git pull",      "action": { "type": "keystroke", "key": "`git pull\n`" } },
      { "label": "git push",      "action": { "type": "keystroke", "key": "`git push\n`" } },
      { "label": "git stash",     "action": { "type": "keystroke", "key": "`git stash\n`" } },
      { "label": "git stash pop", "action": { "type": "keystroke", "key": "`git stash pop\n`" } }
    ],
    "window": {
      "style": "wheel",
      "items": [
        { "label": "Left half",  "action": { "type": "keystroke", "key": "left",  "modifiers": ["ctrl", "opt"] } },
        { "label": "Right half", "action": { "type": "keystroke", "key": "right", "modifiers": ["ctrl", "opt"] } },
        { "label": "Top half",   "action": { "type": "keystroke", "key": "up",    "modifiers": ["ctrl", "opt"] } },
        { "label": "Maximize",   "action": { "type": "keystroke", "key": "f",     "modifiers": ["ctrl", "opt"] } },
        { "label": "Centre",     "action": { "type": "keystroke", "key": "c",     "modifiers": ["ctrl", "opt"] } }
      ]
    }
  }
}

This config:

• Maps the left stick to mouse movement globally, with RB as a speed boost modifier
• Maps the right stick to scrolling globally (inverted Y for natural scroll)
• L3 (left stick click) for left click, with hold for drag — tap clicks, hold drags
• R3 (right stick click) for right click
• Aliases: tmux_leader defined once, reusable across bindings
• Shared modes: media mode available in all profiles for play/pause, track skip, volume
• Default profile: basic arrow keys, space, escape
• Terminal profile: activated for Ghostty, Terminal, and iTerm2
  • shell mode: return, ctrl-c, ctrl-l, git menu on Y (using "type": "menu", "name": "git" syntax)
  • nvim mode: vim-style hjkl navigation, with X+dpad combos for ctrl-j/ctrl-k (half-page scroll)
  • tmux mode: prefix sequences (ctrl-a + key) for pane navigation
  • agent mode: return, escape, and continue as injected text — reached only via context_modes
• Automatic modes: context_modes switches mode from an external token (see Automatic Modes), and hidden_modes keeps agent out of the picker since it is never chosen by hand
• Git menu: quick terminal commands accessible via Y button in shell mode, written as a bare array so it inherits the top-level menu_style
• Window menu: the object form, overriding the default to draw as a circular wheel — both forms can be mixed freely (see Custom Menus)
• Appearance: menu_style sets the default menu presentation and hud_zoom scales every HUD at once (see HUDs)