remap-xi.vercel.app

{
  "name": "get_keyboard_state",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the currently connected keyboard: its name, protocol version, layer count, active layer, and layout options. Call this first to see what keyboard (if any) is connected before using other keymap tools.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_keymap",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the keycodes assigned to every key position (as human-readable QMK keycode strings like \"KC_A\") for one layer, or all layers if none is given. Each entry's array index is the \"keyIndex\" used by remap_key and propose_remap.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layer": {
        "type": "number",
        "description": "Layer index to read; omit to read every layer."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "remap_key",
  "kind": "act",
  "impl": "imperative",
  "description": "Assign a QMK keycode (e.g. \"KC_A\", \"KC_LSFT\", \"MO(1)\") to one key position on a layer. keyIndex is the position in the array returned by get_keymap. Switches the active layer first if it differs from the requested one, so the change is visible on screen. For changing several keys together as one reviewable set, use propose_remap instead.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layer": {
        "type": "number",
        "description": "Target layer index."
      },
      "keyIndex": {
        "type": "number",
        "description": "Key position index, from get_keymap."
      },
      "keycode": {
        "type": "string",
        "description": "QMK keycode string, e.g. \"KC_A\"."
      }
    },
    "required": [
      "layer",
      "keyIndex",
      "keycode"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_active_layer",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch the keyboard configurator UI to show a different layer.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layer": {
        "type": "number"
      }
    },
    "required": [
      "layer"
    ],
    "additionalProperties": false
  }
}

{
  "name": "list_available_keycodes",
  "kind": "answer",
  "impl": "imperative",
  "description": "List QMK keycodes supported by the connected keyboard, for use with remap_key and propose_remap. Use \"search\" to filter (e.g. \"shift\", \"KC_F\") since the full list can be large.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Substring filter, optional."
      },
      "limit": {
        "type": "number",
        "description": "Max results to return, default 60."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "save_keymap_snapshot",
  "kind": "act",
  "impl": "imperative",
  "description": "Export the full keymap (every layer) and macros as a JSON snapshot the agent can hand back to the user or restore later with load_keymap_snapshot.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "load_keymap_snapshot",
  "kind": "act",
  "impl": "imperative",
  "description": "Overwrite the entire keymap (all layers) and macros from a JSON snapshot produced by save_keymap_snapshot. This replaces every key on the keyboard, so it requires user confirmation.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "vendorProductId": {
        "type": "number"
      },
      "layers": {
        "type": "array",
        "items": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "macros": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "vendorProductId",
      "layers"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_lighting_state",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the current RGB/backlight state of the connected keyboard: raw values for v2 keyboards, or the list of controllable lighting/custom options (with current values) for v3+ keyboards.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_lighting_value",
  "kind": "act",
  "impl": "imperative",
  "description": "Set a raw backlight/RGB value on a v2-protocol keyboard. \"command\" is a LightingValue name such as \"BACKLIGHT_BRIGHTNESS\", \"BACKLIGHT_EFFECT\", \"QMK_RGBLIGHT_COLOR\", or \"BACKLIGHT_COLOR_1\". \"values\" is the raw byte payload (e.g. [hue, saturation] for a color, [level] for brightness/effect). Use get_lighting_state first to see supported commands. Only works on v2 keyboards -- use set_custom_menu_option for v3.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string"
      },
      "values": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "required": [
      "command",
      "values"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_custom_menu_option",
  "kind": "act",
  "impl": "imperative",
  "description": "Set a keyboard-defined \"custom menu\" option on a v3+ keyboard, identified by the \"id\" returned from get_lighting_state (covers RGB and other firmware-defined settings). \"value\" is the logical value within the option's [min, max] range.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "value": {
        "type": "number"
      }
    },
    "required": [
      "id",
      "value"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_macro_capabilities",
  "kind": "answer",
  "impl": "imperative",
  "description": "Check whether this keyboard supports macros at all, how many slots it has, the buffer size in bytes, and whether explicit delays are supported in macro expressions. Call this before authoring a long or delay-using macro.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "list_macros",
  "kind": "answer",
  "impl": "imperative",
  "description": "List every macro slot and its current expression text (empty string means unassigned).",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_macro",
  "kind": "act",
  "impl": "imperative",
  "description": "Set the expression for one macro slot, e.g. \"KC_H,KC_I,KC_LSFT(KC_1)\". Use list_macros to see available slot indices and the expression syntax already in use.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "index": {
        "type": "number"
      },
      "expression": {
        "type": "string"
      }
    },
    "required": [
      "index",
      "expression"
    ],
    "additionalProperties": false
  }
}

{
  "name": "clear_macro",
  "kind": "act",
  "impl": "imperative",
  "description": "Clear one macro slot back to empty.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "index": {
        "type": "number"
      }
    },
    "required": [
      "index"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_layout_options",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the physical layout option labels and their currently selected values (e.g. index 0 of a \"Bottom Row\" option meaning ANSI vs ISO).",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_layout_option",
  "kind": "act",
  "impl": "imperative",
  "description": "Set one physical layout option to a new value, from the list returned by get_layout_options.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "optionIndex": {
        "type": "number"
      },
      "value": {
        "type": "number"
      }
    },
    "required": [
      "optionIndex",
      "value"
    ],
    "additionalProperties": false
  }
}

{
  "name": "remap_encoder",
  "kind": "act",
  "impl": "imperative",
  "description": "Assign a QMK keycode to a rotary encoder's clockwise or counter-clockwise rotation on a given layer.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layer": {
        "type": "number"
      },
      "encoderIndex": {
        "type": "number"
      },
      "direction": {
        "type": "string",
        "enum": [
          "cw",
          "ccw"
        ]
      },
      "keycode": {
        "type": "string"
      }
    },
    "required": [
      "layer",
      "encoderIndex",
      "direction",
      "keycode"
    ],
    "additionalProperties": false
  }
}

{
  "name": "navigate_to_pane",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch the app's top-level view. Available panes: default, test, design, console, settings, debug, errors.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pane": {
        "type": "string",
        "enum": [
          "default",
          "test",
          "design",
          "console",
          "settings",
          "debug",
          "errors"
        ]
      }
    },
    "required": [
      "pane"
    ],
    "additionalProperties": false
  }
}

{
  "name": "switch_configure_tab",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch the sub-tab within the Configure pane (Keymap/Lighting/Macros/Layouts/Save + Load). Navigates to the Configure pane first if needed. Not every tab is available on every keyboard.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tab": {
        "type": "string",
        "enum": [
          "Keymap",
          "Lighting",
          "Macros",
          "Layouts",
          "Save + Load"
        ]
      }
    },
    "required": [
      "tab"
    ],
    "additionalProperties": false
  }
}

{
  "name": "reset_eeprom",
  "kind": "transact",
  "impl": "imperative",
  "description": "Erase the keyboard's saved settings (keymap, macros, lighting) back to firmware defaults. Irreversible -- requires user confirmation.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "jump_to_bootloader",
  "kind": "act",
  "impl": "imperative",
  "description": "Reboot the keyboard into its firmware bootloader for reflashing. The keyboard will disconnect. Requires user confirmation.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "propose_remap",
  "kind": "act",
  "impl": "imperative",
  "description": "Propose a set of key changes for a person to review, across one or more keys. This writes nothing to the keyboard. It returns a proposal_id, the exact before and after for every key, and any collisions found against what is already bound. Every change needs its own reason in plain language, because that reason is what the person reviewing it is actually evaluating. Use this for anything touching more than one key; for a single key, use remap_key directly instead.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "rationale": {
        "type": "string",
        "description": "One or two sentences on what this set of changes is for, as a whole."
      },
      "changes": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "object",
          "properties": {
            "layer": {
              "type": "integer"
            },
            "keyIndex": {
              "type": "integer",
              "description": "From get_keymap."
            },
            "keycode": {
              "type": "string",
              "description": "e.g. \"KC_ESC\", \"MO(1)\"."
            },
            "reason": {
              "type": "string",
              "description": "Why this specific key moves."
            }
          },
          "required": [
            "layer",
            "keyIndex",
            "keycode",
            "reason"
          ]
        }
      }
    },
    "required": [
      "rationale",
      "changes"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_proposal",
  "kind": "answer",
  "impl": "imperative",
  "description": "Check what happened to a proposal from propose_remap: still waiting, approved, rejected, written, or reverted.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "proposal_id": {
        "type": "string"
      }
    },
    "required": [
      "proposal_id"
    ],
    "additionalProperties": false
  }
}

{
  "name": "list_connected_devices",
  "kind": "answer",
  "impl": "imperative",
  "description": "List every keyboard this browser currently has WebHID access to: which one is active, which are connected but not selected, and which were seen but could not be used (no definition found, or an unsupported protocol). Pairing a new device is not possible from a tool -- the human has to click \"Authorize device\" -- but this tells an agent what is already available.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "select_device",
  "kind": "act",
  "impl": "imperative",
  "description": "Make a different already-connected keyboard the active one, by path from list_connected_devices. All other tools (keymap, lighting, macros, ...) act on whichever device is active.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string"
      }
    },
    "required": [
      "path"
    ],
    "additionalProperties": false
  }
}

{
  "name": "list_custom_controls",
  "kind": "answer",
  "impl": "imperative",
  "description": "List every keyboard-defined custom setting (toggle, dropdown, button, color, range, or keycode) with its type, label, options, and current value. Covers whatever the keyboard's own firmware definition exposes beyond the keymap -- often lighting, but also anything else the maker defined. Use \"id\" from here with set_custom_control.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_custom_control",
  "kind": "act",
  "impl": "imperative",
  "description": "Set one keyboard-defined custom control, by \"id\" from list_custom_controls. The shape of \"value\" depends on the control's type: toggle wants a boolean, dropdown wants the option's label (string) or explicit value (number), button wants no value at all, color wants {hue, sat} (each 0-255), range and keycode want a single number or keycode string respectively -- list_custom_controls tells you which.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "value": {}
    },
    "required": [
      "id"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_per_key_rgb",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the individual RGB color (hue, saturation, each 0-255) of every key that has its own addressable LED. Only meaningful on v3+ keyboards with per-key lighting; returns an empty list otherwise.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_per_key_rgb",
  "kind": "act",
  "impl": "imperative",
  "description": "Set the RGB color of one key with its own addressable LED, by keyIndex from get_keymap. hue and sat are each 0-255. Only works on v3+ keyboards with per-key lighting.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "keyIndex": {
        "type": "number"
      },
      "hue": {
        "type": "number"
      },
      "sat": {
        "type": "number"
      }
    },
    "required": [
      "keyIndex",
      "hue",
      "sat"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_custom_colors",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the v2-protocol custom color palette (the small set of saved colors some boards offer, indexed 0..N) as a list of {index, hue, sat}.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_custom_color",
  "kind": "act",
  "impl": "imperative",
  "description": "Set one entry in the v2-protocol custom color palette, by index. hue and sat are each 0-255.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "index": {
        "type": "number"
      },
      "hue": {
        "type": "number"
      },
      "sat": {
        "type": "number"
      }
    },
    "required": [
      "index",
      "hue",
      "sat"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_app_settings",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the configurator app's own display preferences: theme (light/dark), theme name, keyboard render mode (2D/3D), and macro editor behavior. This is about the app, not the connected keyboard.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_theme_mode",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch the app between light and dark mode.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "mode": {
        "type": "string",
        "enum": [
          "light",
          "dark"
        ]
      }
    },
    "required": [
      "mode"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_render_mode",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch the on-screen keyboard between a 2D and 3D render. Falls back to 2D automatically if this browser doesn't support WebGL.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "mode": {
        "type": "string",
        "enum": [
          "2D",
          "3D"
        ]
      }
    },
    "required": [
      "mode"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_app_errors",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the app's internal error log -- failed HID commands, device-loading retries, and similar. Useful for diagnosing \"why didn't that work\" without asking the person to open DevTools.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "clear_app_errors",
  "kind": "act",
  "impl": "imperative",
  "description": "Clear the app's internal error log.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_activity_log",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read this agent's own recent tool calls -- name, input, result or error, and timing -- the same feed shown in the Agent Dock's Activity tab. Lets an agent check what it already did instead of relying on conversation memory, e.g. after a page reload mid-task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "number",
        "description": "Max entries to return, newest first. Default 20."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "get_host_keyboard_layout",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the OS keyboard layout the app assumes when showing keycodes (e.g. \"keymap_us\"). This affects display only, not what's written to the device.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_host_keyboard_layout",
  "kind": "act",
  "impl": "imperative",
  "description": "Set the OS keyboard layout the app assumes for display purposes (e.g. \"keymap_us\", \"keymap_uk\", \"keymap_dvorak\"). Does not change anything on the device itself.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layout": {
        "type": "string"
      }
    },
    "required": [
      "layout"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_test_keyboard_sound",
  "kind": "act",
  "impl": "imperative",
  "description": "Configure the app's own audio feedback for the Key Tester (a synthesized tone per keypress, played by the browser -- not the physical keyboard). Omit any field to leave it unchanged.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "isEnabled": {
        "type": "boolean"
      },
      "volume": {
        "type": "number",
        "description": "0-100."
      },
      "waveform": {
        "type": "string",
        "enum": [
          "sine",
          "square",
          "sawtooth",
          "triangle"
        ]
      },
      "mode": {
        "type": "string",
        "enum": [
          "Random",
          "WickiHayden",
          "Chromatic"
        ]
      },
      "transpose": {
        "type": "number"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "get_definition",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the physical layout of every key: its position/size in key units (x, y, w, h, rotation), its firmware matrix position (row, col), and the keycode currently bound to it on the given layer. Use this instead of get_keymap when the request is spatial (e.g. \"the key left of spacebar\") rather than by keyIndex.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "layer": {
        "type": "number",
        "description": "Layer to resolve keycodes against. Default 0."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "diagnose_matrix",
  "kind": "act",
  "impl": "imperative",
  "description": "Read the live physical switch matrix from the device -- which row/col positions are electrically closed right now. Real-time, not related to what keycodes are assigned; use it to check for a stuck key or a wiring problem, not to read the keymap.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_device_info",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read device identity and health: QMK firmware version, VIA keycodes protocol version (both cached from connection time), and live uptime in milliseconds (a fresh read).",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}