@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