# How to Customize Keybindings in Prime Agent: A Complete Guide

> Learn how to customize keybindings in Prime Agent by editing keybindings.json or using the KeybindingsManager API. Streamline your workflow with personalized shortcuts.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-10

---

**You can customize keybindings in Prime Agent by editing the [`keybindings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keybindings.ts) and defines `TUI_KEYBINDINGS`. This object contains standard editor, viewport, and selection actions used across the terminal interface.

```typescript
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/migrations.ts).

## Customizing Keybindings via Configuration File

The simplest method to customize keybindings is creating a [`keybindings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.json) file in your agent's root directory.

### File Location and Loading Mechanism

Place [`keybindings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.json) in the agent directory (path returned by `getAgentDir()`). During startup, `migrateKeybindingsConfigFile` in [`packages/coding-agent/src/migrations.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```json
{
  "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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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

```typescript
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):

```typescript
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:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.json) is loaded.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`packages/tui/src/keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keybindings.ts) | Defines `TUI_KEYBINDINGS` and `KeybindingsManager` class |
| [`packages/coding-agent/src/core/keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/keybindings.ts) | Extends TUI bindings with `KEYBINDINGS` for application commands |
| [`packages/coding-agent/src/migrations.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/migrations.ts) | Loads and migrates [`keybindings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.json) configurations |
| [`packages/tui/src/keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keys.ts) | Implements low-level key matching logic via `matchesKey()` |

## Summary

- **Customization points**: Edit [`keybindings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.json) require a restart because the configuration loads during initialization through `migrateKeybindingsConfigFile`. However, programmatic changes using `setUserBindings()` apply immediately without restarting the agent.