How to Customize Keybindings in Prime Agent: A Complete Guide

You can customize keybindings in Prime Agent by editing the keybindings.json file in your agent directory or programmatically via the KeybindingsManager.setUserBindings() API.

Prime Agent provides a flexible, layered keybinding system that merges default TUI shortcuts with application-specific commands. Whether you prefer configuration files or runtime code changes, the architecture allows you to override any shortcut without modifying core source files. This guide explains how to locate the configuration, understand the registry architecture, and implement both static and dynamic customizations.

Understanding the Keybinding Architecture

Prime Agent employs a two-layer registry managed by the KeybindingsManager singleton. The system combines base terminal UI bindings with higher-level application commands, then merges user overrides on startup.

Default TUI Keybindings

The foundation layer resides in packages/tui/src/keybindings.ts and defines TUI_KEYBINDINGS. This object contains standard editor, viewport, and selection actions used across the terminal interface.

// packages/tui/src/keybindings.ts
export function getKeybindings(): KeybindingsManager {
    if (!globalKeybindings) {
        globalKeybindings = new KeybindingsManager(TUI_KEYBINDINGS);
    }
    return globalKeybindings;
}

Application-Level Extensions

The coding agent extends these defaults in packages/coding-agent/src/core/keybindings.ts by spreading TUI_KEYBINDINGS into KEYBINDINGS and adding Prime Agent-specific actions like model selection, interrupt handling, and stash commands.

The KeybindingsManager Singleton

KeybindingsManager maintains a global singleton accessible via getKeybindings(). It normalizes input through normalizeKeys(), resolves key conflicts, and provides the matches() method that uses matchesKey() (from packages/tui/src/keys.ts) to compare incoming input against registered shortcuts. The manager loads user configurations during initialization through migrateKeybindingsConfigFile in packages/coding-agent/src/migrations.ts.

Customizing Keybindings via Configuration File

The simplest method to customize keybindings is creating a keybindings.json file in your agent's root directory.

File Location and Loading Mechanism

Place keybindings.json in the agent directory (path returned by getAgentDir()). During startup, migrateKeybindingsConfigFile in packages/coding-agent/src/migrations.ts loads this file and passes it to KeybindingsManager, which merges your overrides with the default definitions.

The file maps keybinding IDs to key strings or arrays of strings:

{
  "tui.input.submit": ["enter", "ctrl+enter"],
  "app.prompt.stash": "ctrl+s",
  "app.model.select": ["ctrl+l", "f2"]
}

• Use single strings for one-key shortcuts or arrays for multiple bindings
• Omit any IDs you don't want to override (they retain defaults)
• The system automatically detects conflicts where the same key maps to multiple actions

Applying Changes

Restart Prime Agent after saving keybindings.json. The manager reads this file during initialization and applies your overrides globally.

Programmatic Customization at Runtime

For extensions or dynamic configuration, use the setUserBindings() method on the singleton instance.

Runtime Override Example

import { getKeybindings } from "@earendil-works/pi-tui";

const kb = getKeybindings();
kb.setUserBindings({
  "app.interrupt": "ctrl+q",
  "tui.select.confirm": ["enter", "space"]
});

This approach immediately updates the registry without requiring a restart. All components referencing getKeybindings() automatically receive the new mappings because the manager is a global singleton.

Inspecting and Debugging Keybindings

Prime Agent provides utilities to verify your configuration and identify conflicts.

Viewing Effective Bindings

To see the fully resolved keybinding map (defaults + user overrides):

import { getKeybindings } from "@earendil-works/pi-tui";

const kb = getKeybindings();
console.log(kb.getResolvedBindings());

This outputs the complete mapping currently active in the session.

Detecting Conflicts

Use getConflicts() to find keys assigned to multiple actions:

import { getKeybindings } from "@earendil-works/pi-tui";

const conflicts = getKeybindings().getConflicts();
if (conflicts.length) {
  console.warn("Keybinding conflicts detected:", conflicts);
}

The manager populates this array during the normalization phase when setUserBindings() is called or when keybindings.json is loaded.

Key Implementation Files

File	Purpose
packages/tui/src/keybindings.ts	Defines TUI_KEYBINDINGS and KeybindingsManager class
packages/coding-agent/src/core/keybindings.ts	Extends TUI bindings with KEYBINDINGS for application commands
packages/coding-agent/src/migrations.ts	Loads and migrates keybindings.json configurations
packages/tui/src/keys.ts	Implements low-level key matching logic via matchesKey()

Summary

• Customization points: Edit keybindings.json in the agent directory for static changes, or call KeybindingsManager.setUserBindings() for dynamic updates
• Architecture: The system merges TUI_KEYBINDINGS with application-specific KEYBINDINGS, then applies user overrides through a global singleton
• Conflict detection: The manager automatically identifies duplicate key assignments via getConflicts()
• No restart required: Runtime changes take effect immediately; file-based changes require a restart
• Validation: Use getResolvedBindings() to inspect the active configuration and verify your customizations

Frequently Asked Questions

Where is the keybindings.json file located?

Prime Agent looks for keybindings.json in the agent's root directory (returned by getAgentDir()). If the file doesn't exist, the application uses default bindings exclusively. Create this file manually to begin customization.

Can I bind multiple keys to the same action?

Yes. The configuration supports arrays of strings for multiple shortcuts. For example, "tui.input.submit": ["enter", "ctrl+enter"] allows either key to trigger the action. You can also call setUserBindings() with array values programmatically.

How do I detect if my custom keybindings conflict?

Call getKeybindings().getConflicts() after loading your configuration. The method returns an array of conflicting key definitions detected during the normalization process. Resolve these by ensuring each physical key combination maps to only one action ID.

Do I need to restart Prime Agent after changing keybindings?

File-based changes via keybindings.json require a restart because the configuration loads during initialization through migrateKeybindingsConfigFile. However, programmatic changes using setUserBindings() apply immediately without restarting the agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}