> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyboard Configuration

> Customize keybindings, switch between keymaps, and configure keyboard behavior in Fresh

## Keybinding Maps

Fresh provides several built-in keybinding maps to match different editing styles:

<Tabs>
  <Tab title="Default">
    Standard keybindings inspired by modern editors like VS Code:

    * `Ctrl+P` - Quick open (files, commands, buffers)
    * `Ctrl+S` - Save file
    * `Ctrl+Z` / `Ctrl+Y` - Undo / Redo
    * `Ctrl+F` - Find in file
    * Arrow keys for navigation
    * `Shift+Arrow` for selection
  </Tab>

  <Tab title="Emacs">
    Classic Emacs keybindings:

    * `M-x` (Alt+X) - Command palette
    * `C-f/b/n/p` - Move right/left/down/up
    * `C-a/e` - Line start/end
    * `M-f/b` - Word movement
    * `C-w` - Cut, `M-w` - Copy, `C-y` - Yank (paste)
    * `C-k` - Kill to end of line
    * `C-s/r` - Search forward/backward
  </Tab>

  <Tab title="VSCode">
    VSCode-compatible keybindings (inherits from default with minor tweaks)
  </Tab>

  <Tab title="macOS">
    macOS-specific keybindings that work around terminal limitations:

    * Uses `Ctrl+Alt` instead of `Ctrl+Shift` (which doesn't work in most macOS terminals)
    * `Ctrl+A/E` for line start/end (Home/End don't work properly)
    * Avoids Alt+letter combinations (used for special characters on international keyboards)
    * Respects Unix readline conventions (`Ctrl+Y`, `Ctrl+K`, `Ctrl+U`)
  </Tab>

  <Tab title="macOS GUI">
    macOS GUI-style keybindings (for terminals with full keyboard support like Kitty)
  </Tab>
</Tabs>

## Switching Keymaps

Change the active keymap in your `config.json`:

```json config.json theme={null}
{
  "active_keybinding_map": "emacs"
}
```

**Available maps:**

* `"default"` - Standard editor keybindings
* `"emacs"` - Emacs-style keybindings
* `"vscode"` - VS Code keybindings
* `"macos"` - macOS terminal-friendly keybindings
* `"macos-gui"` - macOS GUI keybindings

<Note>
  On macOS, Fresh defaults to the `"macos"` keymap which handles terminal-specific keyboard limitations.
</Note>

You can also switch keymaps at runtime:

* **Via menu**: View → Keybinding Style → \[Select keymap]
* **Via command palette**: `Ctrl+P` then type `>switch keybinding map`

## Custom Keybindings

Add custom keybindings to override the active keymap:

```json config.json theme={null}
{
  "keybindings": [
    {
      "key": "s",
      "modifiers": ["ctrl"],
      "action": "save",
      "args": {},
      "when": "normal"
    },
    {
      "key": "d",
      "modifiers": ["ctrl", "shift"],
      "action": "delete_line",
      "args": {},
      "when": "normal"
    }
  ]
}
```

### Keybinding Structure

| Field       | Type      | Required | Description                                       |
| ----------- | --------- | -------- | ------------------------------------------------- |
| `key`       | string    | Yes      | Key name (e.g., `"a"`, `"Enter"`, `"F1"`)         |
| `modifiers` | string\[] | No       | Modifier keys: `"ctrl"`, `"shift"`, `"alt"`       |
| `action`    | string    | Yes      | Action to perform (e.g., `"save"`, `"move_left"`) |
| `args`      | object    | No       | Arguments for the action                          |
| `when`      | string    | No       | Context condition (e.g., `"normal"`, `"insert"`)  |

### Key Names

**Letter keys**: `"a"`, `"b"`, `"c"`, ... `"z"`, `"A"`, `"B"`, ...

**Special keys**:

* `"Enter"`, `"Tab"`, `"Backspace"`, `"Delete"`, `"Escape"`
* `"Space"`, `"Home"`, `"End"`, `"PageUp"`, `"PageDown"`
* `"Left"`, `"Right"`, `"Up"`, `"Down"`
* `"F1"` ... `"F12"`

**Modifier keys**: `"ctrl"`, `"shift"`, `"alt"`

### Context Conditions

| Context                   | Description                                   |
| ------------------------- | --------------------------------------------- |
| `"global"`                | Active everywhere                             |
| `"normal"`                | Active in normal editing mode                 |
| `"insert"`                | Active in insert mode                         |
| `"file_explorer_focused"` | Active when file explorer has focus           |
| `"has_selection"`         | Active when text is selected                  |
| `"lsp_available"`         | Active when LSP is running for current buffer |

### Example: Custom Keybindings

```json theme={null}
{
  "keybindings": [
    {
      "comment": "Save with Ctrl+S",
      "key": "s",
      "modifiers": ["ctrl"],
      "action": "save",
      "when": "normal"
    },
    {
      "comment": "Duplicate line",
      "key": "d",
      "modifiers": ["ctrl", "shift"],
      "action": "duplicate_line",
      "when": "normal"
    },
    {
      "comment": "Open file explorer",
      "key": "e",
      "modifiers": ["ctrl"],
      "action": "toggle_file_explorer",
      "when": "global"
    }
  ]
}
```

## Chord Keybindings

Define multi-key sequences (like Emacs `C-x C-s`):

```json theme={null}
{
  "keybindings": [
    {
      "keys": [
        {"key": "x", "modifiers": ["ctrl"]},
        {"key": "s", "modifiers": ["ctrl"]}
      ],
      "action": "save",
      "when": "normal"
    }
  ]
}
```

## Custom Keymaps

Create your own named keymaps:

```json config.json theme={null}
{
  "keybinding_maps": {
    "my-custom-map": {
      "inherits": "default",
      "bindings": [
        {
          "key": "s",
          "modifiers": ["ctrl"],
          "action": "save"
        }
      ]
    }
  },
  "active_keybinding_map": "my-custom-map"
}
```

Custom keymaps can inherit from built-in maps and add or override specific bindings.

## Common Actions

Here are some frequently used actions for custom keybindings:

### File Operations

```json theme={null}
{"action": "save"}           // Save current file
{"action": "save_as"}        // Save as...
{"action": "open"}           // Open file
{"action": "new"}            // New file
{"action": "close"}          // Close buffer
{"action": "quit"}           // Quit editor
```

### Navigation

```json theme={null}
{"action": "move_left"}      // Move cursor left
{"action": "move_right"}     // Move cursor right
{"action": "move_up"}        // Move cursor up
{"action": "move_down"}      // Move cursor down
{"action": "move_word_left"} // Move word left
{"action": "move_word_right"} // Move word right
{"action": "move_line_start"} // Move to line start
{"action": "move_line_end"}   // Move to line end
{"action": "goto_line"}      // Go to line number
```

### Editing

```json theme={null}
{"action": "undo"}           // Undo
{"action": "redo"}           // Redo
{"action": "cut"}            // Cut selection
{"action": "copy"}           // Copy selection
{"action": "paste"}          // Paste
{"action": "delete_line"}    // Delete current line
{"action": "duplicate_line"} // Duplicate line
```

### Search

```json theme={null}
{"action": "search"}         // Find in file
{"action": "find_next"}      // Find next match
{"action": "find_previous"}  // Find previous match
{"action": "query_replace"}  // Find and replace
```

### LSP

```json theme={null}
{"action": "lsp_hover"}           // Show hover info
{"action": "lsp_goto_definition"} // Go to definition
{"action": "lsp_references"}      // Find references
{"action": "lsp_rename"}          // Rename symbol
{"action": "lsp_code_actions"}    // Show code actions
{"action": "lsp_completion"}      // Show completions
```

### UI

```json theme={null}
{"action": "command_palette"}     // Open command palette
{"action": "quick_open"}          // Quick open files
{"action": "toggle_file_explorer"} // Toggle file explorer
{"action": "split_horizontal"}    // Split horizontally
{"action": "split_vertical"}      // Split vertically
```

## Viewing Current Keybindings

To see all active keybindings:

1. **Command palette**: `Ctrl+P` → `>Show Keybindings`
2. **Menu**: Help → Keyboard Shortcuts
3. **Direct file**: View the keymap file at `keymaps/[name].json`

## macOS Terminal Configuration

macOS terminals have specific keyboard limitations. See the complete guide below:

<AccordionGroup>
  <Accordion title="macOS Terminal Setup Guide">
    ### macOS Keymap

    Fresh includes a dedicated macOS keymap that addresses terminal-specific challenges. To use it:

    ```json theme={null}
    {
      "active_keybinding_map": "macos"
    }
    ```

    The macOS keymap works around these limitations:

    **Ctrl+Shift combinations don't work.** Some macOS terminals cannot reliably send Ctrl+Shift sequences. The macOS keymap uses Ctrl+Alt as an alternative modifier.

    **Some Ctrl keys are ASCII control characters.** Terminal protocols treat Ctrl+J as Line Feed, Ctrl+M as Carriage Return, and Ctrl+I as Tab. The macOS keymap avoids these collisions.

    **International keyboards use Alt for essential characters.** On German, French, and other ISO layouts, Alt (Option) combined with letters produces characters like @, \[, ], \{, }. The macOS keymap avoids blocking character input.

    ### Recommended Terminals

    | Terminal         | Support | Configuration                                       |
    | ---------------- | ------- | --------------------------------------------------- |
    | **Kitty**        | Full    | Add `macos_option_as_alt left` to config            |
    | **Ghostty**      | Full    | Add `macos-option-as-alt = left` to config          |
    | **iTerm2**       | CSI u   | Enable "Report keys using CSI u" in Settings        |
    | **Terminal.app** | Manual  | Import Fresh.terminal profile or configure manually |

    ### iTerm2 Setup

    1. Go to **Settings** → **Profiles** → **Keys**
    2. Check **Report keys using CSI u**
    3. Set **Left Option key** to **Esc+**
    4. Set **Right Option key** to **Normal** (for special characters)

    ### Terminal.app Setup

    **Import Profile** (easiest):

    1. Locate `scripts/macOS/Fresh.terminal` in the repository
    2. In Terminal.app, go to **Settings** → **Profiles**
    3. Click the gear icon and select **Import...**
    4. Select the `Fresh.terminal` file

    **Manual Configuration**:

    1. Settings → Profiles → Keyboard → Check **Use Option as Meta key**
    2. Add key mappings for Shift+Arrow keys:
       * Shift+Up: `\033[1;2A`
       * Shift+Down: `\033[1;2B`
       * Shift+Left: `\033[1;2D`
       * Shift+Right: `\033[1;2C`

    ### Mission Control Conflicts

    macOS uses Ctrl+Arrow for desktop switching. To use Ctrl+Arrow in Fresh:

    1. Open **System Settings** → **Keyboard** → **Keyboard Shortcuts** → **Mission Control**
    2. Disable or rebind:
       * "Move left a space" (Ctrl+Left)
       * "Move right a space" (Ctrl+Right)
       * "Mission Control" (Ctrl+Up)
       * "Application windows" (Ctrl+Down)
  </Accordion>
</AccordionGroup>

## Keyboard Enhancement Flags

Configure advanced keyboard protocol features:

```json config.json theme={null}
{
  "editor": {
    "keyboard_disambiguate_escape_codes": true,
    "keyboard_report_event_types": false,
    "keyboard_report_alternate_keys": true,
    "keyboard_report_all_keys_as_escape_codes": false
  }
}
```

| Option                                     | Default | Description                                    |
| ------------------------------------------ | ------- | ---------------------------------------------- |
| `keyboard_disambiguate_escape_codes`       | `true`  | Use CSI-u for unambiguous escape/modifier keys |
| `keyboard_report_event_types`              | `false` | Report key repeat and release events           |
| `keyboard_report_alternate_keys`           | `true`  | Send alternate keycodes                        |
| `keyboard_report_all_keys_as_escape_codes` | `false` | Report all keys as escape sequences            |

<Warning>
  If you experience keyboard issues, try disabling all flags by setting them to `false`.
</Warning>

## Linux: XFCE Window Manager

XFCE captures Ctrl+Alt+Up/Down for workspace switching. To disable:

1. Open **Settings** → **Window Manager** → **Keyboard**
2. Find `Upper workspace` and `Bottom workspace`
3. Click **Clear** for both shortcuts

## Debugging Keyboard Issues

If keybindings aren't working:

1. **Debug keyboard events**: Help → Debug Keyboard Events
2. See what your terminal sends for each keypress
3. Adjust keybindings or terminal configuration accordingly

See [Troubleshooting: Debug Keyboard Events](/reference/troubleshooting#debug-keyboard-events) for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Settings Reference" icon="sliders" href="/configuration/settings">
    Complete editor configuration options
  </Card>

  <Card title="Theme Configuration" icon="palette" href="/configuration/themes">
    Customize colors and themes
  </Card>
</CardGroup>