~/vimma/docs $ less config.md

config.toml

Everything you can change about Vimma's keys and behaviour lives in one file: ~/.config/vimma/config.toml. Until you change something in it, you get the defaults.

Edit the file

1. Vimma creates the file on a profile's first launch, with every default written out and commented, so it changes nothing yet; the status bar says created ~/.config/vimma/config.toml once. A file you already have is never touched. :config shows it in a tab.
2. Open it in your editor, uncomment or add what you want to change, and save.
3. Vimma picks it up within two seconds, in every window. Nothing to restart. :source reloads it at once.

Remap a key

Bindings go under [keys], by the action names in the Name column of the keys page. prefix+ means after ctrl+b. A new binding replaces the default.

schema = 2

[keys]
prefix = "ctrl+a"             # the prefix itself, as tmux users often remap it
new_tab = ["prefix+t"]        # ctrl+a t opens a tab, instead of the default

[modal]
leader = ","                  # the leader key; space by default

[modal.normal]
"<leader>ff" = "goto.picker"  # , f f lists every tab

Other things you can set

Keep schema = 2 as the first line: it enables [panes], [sites], [firefox], insert_editing and hint characters.

If you make a mistake

A file with an error is not applied at all, so your last working setup keeps working. The status bar shows the first error in red, with its line number, for example config.toml:3: keys.new_tabb: unknown action "new_tabb" (did you mean "new_tab"?). Fix the line and save; the message goes away. about:vimma lists every error.

about:config and about:vimma

A few switches live in about:config instead, such as vimma.ui.tabstrip.hidden to bring Firefox's tab strip back; they are listed under Details. about:vimma (or :about) shows what Vimma is doing: its version, your config and its errors, the theme, the workspaces, and the last keys it saw.

All the keys for this page

The default bindings, as Vimma's own ctrl+b ? overlay lists them. Name is the action's name, which you use to remap it or to run it as a : command. Every key is on the keys page.

Details

Everything below is Vimma's own user guide for this topic, in full: every edge case and exception. You do not need it to get started.

Every key is yours

The keys in this guide are defaults, not decisions. Every binding, the ctrl+b prefix and the space leader can be remapped in ~/.config/vimma/config.toml. The leader has no default bindings; it is there for your own. These three lines move the prefix to ctrl+a, move the leader to ,, and add a leader binding (, n) for the side panel:

keys.prefix = "ctrl+a"                           # the prefix, ctrl+b by default as in tmux
modal.leader = ","                               # the leader, space by default as in many Vim setups
keys.toggle_sidebar = ["prefix+b", "<leader>n"]  # side panel: prefix b, and now also leader n

Save the file and the change applies within 2 seconds, without a restart. config.toml has the details, and bindings.md lists every action's config name with its default keys.

Vimma reads ~/.config/vimma/config.toml ($XDG_CONFIG_HOME/vimma/config.toml when that is set), and nothing else in that folder. No file means the defaults. Vimma creates it, with every default commented out under a short header on how to edit it, in two cases: on a profile's first run, and when you type :config (which then opens it in a tab). The folder is created mode 0700 if it is missing, and the file mode 0600, since it can name intranet hosts. An existing file, even an empty one, is never written; :route add only appends to it. A small example:

schema = 2

[keys]
new_tab = ["prefix+t"]        # replaces ctrl+b c

[modal.normal]
"<leader>ff" = "goto.picker"

[panes]
max = 2

[theme]
source = "file"               # Tokyo Night instead of your Omarchy theme
[theme.colors]
accent = "#ff9e64"

• Notation: prefix+t means the prefix ([keys] prefix, default ctrl+b), then t; <leader>ff means the leader ([modal] leader, default space), then f f; keys in a sequence are separated by spaces. The ctrl+b ? overlay, :map and about:vimma show bindings as the keys you press, with your prefix and leader.
• Reload: save the file and Vimma picks it up within 2 seconds, in every window, without a restart. :source reads it at once.
• Another file: :source work.toml loads that file instead, the same way: whole, over the defaults, not merged into config.toml (a file is checked as a whole, so two half-configs could not be). A relative path is next to config.toml; ~, $HOME and $XDG_CONFIG_HOME expand at its start. It stays in force until config.toml changes or you type a plain :source. A missing or broken file changes nothing and shows its error in the status bar under its own name (work.toml: no such file, work.toml:3: …).
• Errors: a file with a mistake is not applied at all: the config you had keeps working, and the status bar shows the first mistake in red on the right, with its line, e.g. config.toml:3: keys.new_tabb: unknown action "new_tabb" (did you mean "new_tab"?) (or 3 errors: …). The Browser Console (ctrl+shift+j) lists them all. Fix the file and the message goes away at the next check.
• What applies live: [keys], [modal] (leader, timeout_ms, per-mode keys, hint_chars) and [unbind]; [panes] max (most panes in a workspace, 1 to 16, default 4; it limits new splits), [panes] layout ("dwindle" or "manual": where ctrl+b enter puts a new pane) and [panes] main_size (the main-\* presets' main pane, 20 to 80 percent, default 60); [sites."<host>"] insert (auto, never or always: whether a text field on that site and its subdomains takes insert mode); [theme] source (omarchy or file, the built-in Tokyo Night), font and [theme.colors] (single colours over either source); [workspaces] (a new one gets its container at once; one removed from the file stays, as a workspace you can close yourself); [firefox] disable and enable (which of Firefox's own shortcuts are off, above); [modal] insert_editing (ctrl+w, ctrl+u, ctrl+h in text fields, default true); [bookmarks] root ("workspace", the default: the current workspace's folder; "toolbar"; or "all": what the bookmarks panel lists and where paths start).
• Schema: schema = 2 at the top enables [panes], [sites], [firefox], [bookmarks], hint_chars and insert_editing; packages/vimma-core/defaults.toml lists them with their defaults.

Settings (about:config)

Vimma's own preferences today:

about:vimma

about:vimma (or :about) shows what Vimma is doing, as of when the page opened: press r or Refresh for the current state. It is an ordinary page, so j / k scroll it.

• Version: Vimma's version, the Firefox release it is built on, the build ID and the update channel.
• Upstream patches: how many patches to Firefox's own files the build carries, each with its hunk count (the fewer, the easier a Firefox update).
• Modes and keys: each window's mode, and the last 20 keys Vimma saw with what each did (j → scroll.down, pass when the key went to the page). Letters typed into a text field or the command line show as ·, so nothing you type is kept.
• Config: the config.toml path, whether it was read, its schema, every error with its line, and the full binding table with the keys your file changes marked *.
• Theme: the colour source, the Omarchy theme directory, the theme's name and its colors.toml time, and why the last theme file was rejected, if one was.
• Workspaces: how many there are, and this window's with their tab and pane counts.
• Control socket: on or off, and its port. The token is never shown.

Copy redacted report (or :bug) copies all of that as text, without the binding table's defaults, with every URL replaced by <url> and your home directory by ~. It never contains page titles or addresses.

Known limits

Vimma is pre-alpha. What does not work yet, or works with a catch, is listed on the known limits page:

• Features

The guide at the top is written for this site; the details are built from Vimma's docs/guide.md and bindings.md at 1050bcc (2026-10-10).