@vahor/pi-keymap

Define Vim-like custom keymaps that bind keyboard shortcuts to shell commands.

pi install npm:@vahor/pi-keymap

Config

Configuration is loaded from both locations and merged recursively. keymaps arrays are merged by key, so project entries replace global entries with the same key:

| Location | Scope | |----------|-------| | ~/.pi/agent/keymap.json | Global keymaps | | .pi/keymap.json | Project keymaps; overrides global values |

If neither file exists, the extension creates .pi/keymap.json with an empty config and a $schema field for editor validation.

// .pi/keymap.json
{
  "leader": "space",
  "keymaps": [
    // Direct shortcuts
    {
      "key": "ctrl+shift+t",
      "commands": ["bun run test"]
    },
    // Leader-prefixed shortcuts (triggered via leader key + sub-key)
    {
      "key": "<leader>f",
      "description": "Format",
      "commands": [{ "command": "bun run format", "timeout": 1000, "print": true }]
    },
    {
      "key": "<leader>p",
      "description": "Draft prompt in pi editor",
      "prompt": "Default prompt content",
      "send": false,
      "open": true
    },
    {
      "key": "<leader>g",
      "description": "Git",
    },
    // Nested leader keys
    {
      "key": "<leader>gg",
      "commands": [{ "command": "lazygit", "interactive": true }]
    },
  ]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | leader | string | Yes | Key that activates the which-key overlay | | keymaps | array | Yes | List of keymap entries | | keymaps[].key | string | Yes | Key combination or <leader>key | | keymaps[].description | string | No | Label shown in the which-key overlay (falls back to first command) | | keymaps[].commands | array | No | Shell commands to run. Required for command keymaps. | | keymaps[].prompt | string | No | Default prompt text. | | keymaps[].send | boolean | No | For prompt keymaps, send saved content immediately instead of placing it in the input editor. Defaults false | | keymaps[].open | boolean | No | For prompt keymaps, open editor before using the prompt. Defaults true; false uses the prompt immediately according to send. | | keymaps[].print | boolean | No | Print command output in the UI. Defaults true | | keymaps[].context | boolean | No | Add command output to the agent context | | keymaps[].interactive | boolean | No | Default interactive mode for commands in this keymap |

commands, prompt, and grouping entries are mutually exclusive shapes: use commands for shell commands, prompt for prompt drafts, or neither for a leader grouping node. print, context, and interactive can be overridden at command level. Command-level wins over keymap-level.

Key format

modifier+key where modifiers are ctrl, shift, alt, super (e.g. ctrl+shift+p, alt+x).

Valid base keys:

| Category | Keys | |----------|------| | Letters | a–z | | Digits | 0–9 | | Named | escape, esc, enter, return, tab, space, backspace, delete, insert, clear, home, end, pageUp, pageDown | | Arrows | up, down, left, right | | Function | f1–f12 | | Symbols | `, -, =, [, ], \, ;, ', ,, ., /, !, @, #, $, %, ^, &, *, (, ), _, +, \|, ~, {, }, :, <, >, ? |

Invalid keys are warned at startup and skipped.

Command format

Each entry can be a string (just the command) or an object:

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | command | string | Yes | – | Shell command to run | | cwd | string | No | project root | Working directory (relative) | | timeout | number | No | 30000 | Timeout in milliseconds | | print | boolean | No | true | Render command output in pi | | context | boolean | No | false | Add command output to the agent context | | interactive | boolean | No | false | Suspend pi's TUI and run with full terminal access. Use for commands like lazygit, vim, htop, or fzf. Output is not captured. |

Command output is rendered in pi when print or context is enabled. Interactive commands restore and fully redraw pi after they exit.

Leader key & which-key overlay

Press the configured leader key to open a full-width bottom overlay listing all leader-prefixed keymaps. The overlay only opens when the input editor is empty, so typing a space (if your leader is space) won't accidentally trigger it. Press the sub-key to run the mapping, or escape to dismiss. The overlay auto-closes after 5 seconds.

Leader keys can be nested: <leader>g shows a sub-overlay with its children (gp → git push, gpf → git push --force). Prefix-only nodes (no commands, just a description) act as grouping folders.

Which-key entry styles:

| Mapping state | Style | |---------------|-------| | Default command | Accent key | | print: false | Accent key, appends dim (silent) | | context: true | Prefixed with # | | interactive: true | Prefixed with $ | | Prefix/group node | Warning key + purple + label | | Labels | Purple for groups, soft orange for actions |