flow-website/content/docs/architecture/keybind.smd

---
.title = "Keybinding",
.date = @date("2025-10-19T00:00:00"),
.author = "Igor Támara",
.layout = "tutorial.shtml",
.draft = false,
.custom = {
  .githubedit = "/docs/architecture/keybind.smd",
  .codepath ="src/keybind/builtin/",
},
---

If you are here, maybe is because you want to make flow behave according
to your key presses preferences or possibly you already have edited your
own keybinds to suit your needs and are looking for some advanced
topics to cope your use cases and make everything easier and
fluid when in Flow.

Using the command palette `Ctrl+Shift+p` and typing **Edit key
bindings**, takes you to the json file to extend Flow configuring
keybindings to suit your needs. According to the mode you are in, the
corresponding file will be opened. The palette can also be reached left
clicking on the current mode in the status bar.

[]($section.id('tldr'))
## ;TLDR;

Once you open the corresponding json file, locate inside the imode
(internal mode) that will accept the key or keys/combo and add an array,
where the first element is the combination to map to the commands that
will happen, the array accepts strings like in

```js
["ctrl+alt+shift+p", "open_command_palette"]
```

To avoid screwing up the combinations, and putting Flow in an unusable
state derived from a wrong mapping of key combinations, read on.

[]($section.id('defaults'))
## Resetting keys to factory defaults

User configured keybindings are stored in Flow's configuration directory
under `keys/mode.json` where mode can be `flow`, `emacs`, `vim`, `helix`
or customized ones. Removing the keys directory or the particular mode
file can take you out from a broken state.

[]($section.id('modes'))
## Keybinds for each mode

Keybinds are edited per mode, and other modes inherit what is defined
in your `flow.json` keybindings. Each mode override keybindings of its
parent mode. For example, if you are in **emacs** mode you will be
redirected to `emacs.json` and it will override the keybindings from
flow.

[introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases
how to get to edit keybindings.

[]($section.id('hierarchy'))
## Keybindings hierarchy

Some terminology

* **Mode**: Stored in a json file, like flow mode declared in
`flow.json`.
* **Imode**: under the json file.
* **Major Imode**: `project` or descendant from `project`.
* **Minimodes**: To be used momentarily and do not inherit from
`project`.

In general a keybinding json shows this hierarchy:

```
Mode > Imode > press > Key and commands
map > map   > array > array(array(string,numbers),strings,numbers)
```

`Mode` is the json file that holds a map, where each entry has a map
called `press` that is an array of arrays.

`project` is the main imode in `flow.json` and it can be noticed that
`normal` imode `inherit`s from `project`, some modes have `release`,
usually one will be using only `press` inside `normal` imode or the
specific mode if inside `vim`, `helix` or `emacs` modes.

Looking further, it can be seen that
[minimodes](/docs/architecture/minimode) have their keybinding mappings
defined in a particular imode.

As stated previously, there is a mode hierarchy, the main mode is flow
and other modes inherit from it. We remind that also imodes have a
hierarchy and it's common for major imodes to be descendants from
`project`.

[]($section.id('adding'))
## Adding a Keybinding

The most basic case to map a keybind to a command was covered in
[TLDR](#tldr) which used the combination of three keys pressed
simultaneously `ctrl`, `shift` and `p`, all of them where combined with
`+` to execute the command `open_command_palette`.

A common use case is to add a keybinding to invoke an already existing
command and chain it to another, making Flow more suited to your own
needs.

[]($section.id('shell'))
## Running shell commands

For example, `f5` by default is used to run `zig build test` outputting
its results to a *scratch buffer* called `test`.

```js
["f5", ["create_scratch_buffer", "*test*"], ["shell_execute_insert", "zig", "build", "test"]],
```

Note that:

The keybind is `f5`, which maps to the `f5` keycode. is invoking
`create_scratchbuffer`, receiving the parameter `*test*` which results
in creating a scratch buffer if didn't exist. And then executing the
command `shell_execute_insert` that receives the paramaters `zig`,
`build`, `test`. This latter command is executing a shell command
called `zig` with the parameters `build` and `test`; if you don't have
zig installed, it will not work, and you might want to remap `f5` to a
different shell command.

```
[
  "f5",
  [
    "create_scratch_buffer",
    "*test*"
  ],
  [
    "shell_execute_insert",
    "zig",
    "build",
    "test"
  ]
]
```

Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe
consider using more keybindings or running tasks for your projects.

[]($section.id('next'))
## Next steps

If you realized that there is a handy combination that others can
benefit from or that a mode lacks the combination and it might be
included in flow, look at the [contribution guidelines](/docs/contributing)
to submit your findings and solution.

Probably binding commands is good, but maybe there is a feature in other
text editors that you miss and would love to have it at your fingertips.
Then it's Zig time:
[Adding commands](/docs/architecture/command) to flow.


* Making flow even better with [tests](/docs/testing)
* [How to contribute](/docs/contributing)
* [Get in touch](https://discord.com/invite/4wvteUPphx) to share your
combos