Mitos

Mitos is a terminal text editor built around selections. Written in Rust and based on Helix, it combines selection-first modal editing with multiple selections, tree-sitter syntax awareness, and built-in language-server support.

Start with the basics · Install Mitos · View the source

ms --tutor

At a glance

What Mitos supports

Editing

• Selection-first modal editing
• Multiple selections as a core operation
• Syntax-aware motions and textobjects
• Registers, macros, search, and surround operations

Code intelligence

• Incremental parsing and highlighting with tree-sitter
• Built-in LSP client for completion and navigation
• Diagnostics, formatting, rename, and code actions
• Debug adapter support

Workflow

• File, buffer, symbol, and diagnostic pickers
• Shell commands and selection pipelines
• Configurable keymaps, themes, and languages
• Workspace trust for project-local configuration

Select first, then act

In Mitos, a cursor is a one-character selection. Motions change or extend that selection, and commands operate on what is selected. The target of an edit is visible before the edit happens.

Multiple selections use the same commands as a single selection. Select every match, press c, and type once to change all of them:

1. Press x to select a line.
2. Press s to select regular-expression matches.
3. Press c to change every selection at once.

Learn more in Basics.

Where it fits

Repeated and structural edits

Multiple selections and tree-sitter textobjects make related edits explicit and let one command operate on every target.

Programming with language tools

Use completion, diagnostics, symbol navigation, formatting, and code actions through the built-in LSP client.

Terminal-based workflows

Open files from the shell, pipe selections through commands, and keep editing close to compilers, version control, and other tools.

Start here

• Installation — install a release or build Mitos from source.
• Basics — learn modes, movement, selections, and common commands.
• Keymap — look up default bindings by mode and command.
• Configuration — configure editor behavior, themes, keys, and languages.
• Language servers — set up completion, diagnostics, formatting, and actions.
• Commands — browse typable and static commands.

About Mitos

Mitos is an independent fork of Helix. It retains the upstream Git history and continues Helix’s selection-first editing model while developing as a separate project.

The editor is open source under the Mozilla Public License 2.0. Mitos is not endorsed by or affiliated with the Helix project or its maintainers.

Basics

Mitos is a modal editor: the same keys navigate, select, and edit depending on the current mode. This short walkthrough covers enough to edit a file without trying to memorize the entire keymap.

For a guided lesson inside the editor, run ms --tutor or enter :tutor from Mitos.

Open a file

After installing Mitos, open a file or directory from your shell:

ms README.md
ms .

Mitos starts in normal mode. Press Esc whenever you want to return to it.

Image previews

Open an image file the same way as a text file, for example ms screenshot.png. See Image previews for supported formats and terminal rendering.

Move around

Use the arrow keys or the home-row movement keys:

You can prefix many movements with a count. For example, 5j moves down five visual lines.

Insert text

From normal mode, press i to insert before the selection or a to append after it. Type normally, then press Esc to finish the insertion.

Other useful entry points are I and A for the start and end of the line, and o / O for a new line below or above.

Select, then act

Mitos uses a selection → action editing model. A cursor is a one-character selection; movement changes that selection. Press v to enter select mode, where movement extends it, then apply an action:

Press x to select the current line. Syntax-aware textobjects, such as miw for the word around the cursor, are described in Textobjects.

Edit several matches at once

Multiple selections are a normal part of editing, not a separate mode. One simple workflow is:

1. Press x to select a line.
2. Press s, enter a regular expression, and press Enter.
3. Mitos creates one selection for every match in the line.
4. Press Alt-r, type the replacement, and press Enter to replace every selection.

The replacement prompt leaves the document untouched until Enter, then replaces all selections in one undo step. Escape cancels, and submitting empty text deletes the selections. Replacement text is literal, including strings such as $1. The new text stays selected, preserving the primary selection and each selection’s direction. Press . to repeat the committed replacement on the current selections.

Use c to change selections interactively in insert mode. r still replaces each selected grapheme with the next character: selecting hello and typing rx gives xxxxx, while Alt-r, x, Enter gives x.

Use , to keep only the primary selection. The Usage and Registers pages cover more ways to compose edits.

Search, save, and quit

Press / to search forward, then use n and N to move between matches. Press : to enter command mode:

Where to go next

• Read Usage for modes, buffers, selections, and motions.
• Keep the Keymap open as a reference while learning.
• Set up language servers for completion, diagnostics, and code actions.
• Adjust editor behavior in Configuration.

Installation

Mitos runs on Linux, macOS, and Windows. The executable is called ms. Use the installer, download a release archive, or install the Debian package. You can also build from source.

Installer

Linux and macOS

curl -fsSL https://mitos.computer/install.sh | sh

The installer selects the right archive, verifies its SHA-256 checksum, and keeps the executable and runtime together in $XDG_DATA_HOME/mitos/ (default: ~/.local/share/mitos/). It links ms into ~/.local/bin, without sudo or changes to your shell files. If that directory is missing from your PATH, it prints the command to add it.

To install a specific version:

curl -fsSL https://mitos.computer/install.sh | sh -s -- --version 0.1.0

Rerun the installer to upgrade. Previous versions stay installed, so running it with an older --version switches back. Use --install-dir and --bin-dir to choose other directories. The installer leaves an existing ms from another installation alone. View the shell installer source.

Windows

Run in PowerShell 5.1 or newer:

& ([scriptblock]::Create((Invoke-RestMethod https://mitos.computer/install.ps1)))

To pin a version, add -Version 0.1.0:

& ([scriptblock]::Create((Invoke-RestMethod https://mitos.computer/install.ps1))) -Version 0.1.0

The installer verifies the ZIP’s checksum, keeps each version and its runtime under %LOCALAPPDATA%\Mitos\versions, and creates an ms.cmd launcher in %LOCALAPPDATA%\Mitos\bin. It adds that directory to your user Path and the current PowerShell session. No administrator access is needed. Use -InstallDir for another location, or -NoModifyPath to manage Path yourself. Rerun to upgrade or select another version. View the PowerShell installer source.

Uninstall

On Linux/macOS, remove the installer-created ~/.local/bin/ms symlink and ~/.local/share/mitos directory. On Windows, remove %LOCALAPPDATA%\Mitos and its bin entry from your user Path. Adjust these paths for custom installs. Your configuration and personal dictionaries remain in the Mitos configuration and state directories.

Release archives

Download the archive for your system from GitHub Releases:

VERSION is the release number, such as 0.1.0. Apple Silicon Macs use aarch64-macos; Intel Macs use x86_64-macos. Linux archives use glibc.

Extract the archive and keep runtime/ beside ms (ms.exe on Windows). It contains the themes, language queries, dictionaries, and compiled grammars. No Rust toolchain or grammar compilation is needed.

Linux and macOS

For example, install version 0.1.0 on an Apple Silicon Mac, using GitHub CLI:

gh release download v0.1.0 --repo mitos-editor/mitos \
  --pattern 'mitos-v0.1.0-aarch64-macos.tar.xz'
mkdir -p "$HOME/.local/share/mitos" "$HOME/.local/bin"
tar -xJf mitos-v0.1.0-aarch64-macos.tar.xz -C "$HOME/.local/share/mitos"
ln -sfn "$HOME/.local/share/mitos/mitos-v0.1.0-aarch64-macos/ms" \
  "$HOME/.local/bin/ms"

For another platform or release, replace the archive and directory names using the table above. You can also download the archive in your browser. Add ~/.local/bin to your shell’s PATH if it is not already there. Mitos follows the executable’s symlink to find the bundled runtime.

Windows

Extract the ZIP to a permanent directory, such as $HOME\Apps\Mitos\mitos-v0.1.0-x86_64-windows. Add that directory to your user Path through Environment Variables, then open a new terminal. Keep ms.exe and runtime/ together.

Debian and Ubuntu

On x86_64 Debian or Ubuntu, download the .deb asset from GitHub Releases, then install it from the download directory:

sudo apt install ./mitos_0.1.0-1_amd64.deb

Use the downloaded package’s filename if it differs. The package includes the runtime, shell completions, and desktop entry. ARM64 users can use the release archive or the installer. If your system’s glibc is too old, see building the Debian package.

Configuration after upgrading

Mitos loads known legacy settings without rewriting your configuration. Use :config-migrate or :config-migrate-workspace to update a file after confirmation, with a backup. Generated and read-only files can be migrated to stdout instead. See configuration migration for details. languages.toml is left unchanged.

Verify the installation

ms --version
ms --health

If the runtime is missing, keep it beside the executable or set MITOS_RUNTIME to its full path. See runtime configuration for the complete search order. Older runtime files in your user configuration can override those bundled with a release.

Language servers are installed separately. See language-server setup to enable completion, diagnostics, and other language features.

Package managers

Mitos is not yet published through third-party package managers. Use the hosted installers or release archives, or build from source.

Debian package

The x86_64 release includes a .deb package. See Debian and Ubuntu installation.

To build a Debian package locally, see Building the Debian package.

Building from source

• Configuring Mitos’s runtime files
  • Linux and macOS
  • Windows
  • Multiple runtime directories
  • Note to packagers
• Validating the installation
• Configure the desktop shortcut
• Building the Debian package

Requirements:

Clone the Mitos GitHub repository into a directory of your choice. The examples in this documentation assume installation into either ~/src/ on Linux and macOS, or %userprofile%\src\ on Windows.

• The Rust toolchain
• The Git version control system
• A C++14 compatible compiler to build the tree-sitter grammars, for example GCC or Clang

If you are using the musl-libc standard library instead of glibc the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:

RUSTFLAGS="-C target-feature=-crt-static"

1. Clone the repository:

   git clone https://github.com/mitos-editor/mitos
   cd mitos
   

2. Compile from source:

   # Optimized release build
   cargo build --release --locked
   

   # Optimized for the current CPU
   cargo install \
      --profile opt \
      --config 'build.rustflags=["-C", "target-cpu=native"]' \
      --path crates/term \
      --locked
   

   The release build creates target/release/ms; the install command places ms in Cargo’s binary directory. Both commands construct the tree-sitter grammars in the local runtime folder. ms is short for Mitos.

💡 If you do not want to fetch or build grammars, set an environment variable MITOS_DISABLE_AUTO_GRAMMAR_BUILD

💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch grammars with ms --grammar fetch and compile them with ms --grammar build. This will install them in the runtime directory within the user’s mitos config directory (more details below).

💡 If you only want to build some grammars, see use-grammars

Configuring Mitos’s runtime files

Linux and macOS

The runtime directory is one below the Mitos source, so either export a MITOS_RUNTIME environment variable to point to that directory and add it to your ~/.bashrc or equivalent:

export MITOS_RUNTIME=~/src/mitos/runtime

Or, create a symbolic link:

ln -Tsf $PWD/runtime ~/.config/mitos/runtime

Windows

Either set the MITOS_RUNTIME environment variable to point to the runtime files using the Windows setting (search for Edit environment variables for your account) or use the setx command in Cmd:

setx MITOS_RUNTIME "%userprofile%\src\mitos\runtime"

💡 %userprofile% resolves to your user directory like C:\Users\Your-Name\ for example.

Or, create a symlink in %appdata%\mitos\ that links to the source code directory:

💡 On Windows, creating a symbolic link may require running PowerShell or Cmd as an administrator.

Multiple runtime directories

When Mitos finds multiple runtime directories it will search through them for files in the following order:

1. The workspace’s runtime/ directory when running through Cargo.
2. runtime/ subdirectory of OS-dependent mitos user config directory.
3. $MITOS_RUNTIME
4. Distribution-specific fallback directory (set at build time with MITOS_DEFAULT_RUNTIME).
5. runtime/ subdirectory of path to Mitos executable.

This order also sets the priority for selecting which file will be used if multiple runtime directories have files with the same name.

ms --grammar fetch and ms --grammar build write grammar sources and compiled grammars into the first runtime directory, normally the user config directory’s runtime/ subdirectory.

Note to packagers

If you are making a package of Mitos for end users, to provide a good out of the box experience, you should set the MITOS_DEFAULT_RUNTIME environment variable at build time (before invoking cargo build) to a directory which will store the final runtime files after installation. For example, say you want to package the runtime into /usr/lib/mitos/runtime. The rough steps a build script could follow are:

1. export MITOS_DEFAULT_RUNTIME=/usr/lib/mitos/runtime
2. cargo build --profile opt --locked
3. cp -r runtime $BUILD_DIR/usr/lib/mitos/
4. cp target/opt/ms $BUILD_DIR/usr/bin/ms

This way the resulting ms binary will always look for its runtime directory in /usr/lib/mitos/runtime if the user has no custom runtime in ~/.config/mitos or MITOS_RUNTIME.

Validating the installation

To make sure everything is set up as expected you should run the Mitos health check:

ms --health

The command reports runtime, clipboard, language-server, and grammar status.

Configure the desktop shortcut

If your desktop environment supports the XDG desktop menu you can configure Mitos to show up in the application menu by copying the provided .desktop file:

cp contrib/Mitos.desktop ~/.local/share/applications

It is recommended to convert the links in the .desktop file to absolute paths to avoid potential problems:

sed -i -e "s|Exec=ms %F|Exec=$(readlink -f ~/.cargo/bin/ms) %F|g" \
  ~/.local/share/applications/Mitos.desktop

To use another terminal than the system default, you can modify the .desktop file. For example, to use kitty:

sed -i "s|Exec=ms %F|Exec=kitty ms %F|g" ~/.local/share/applications/Mitos.desktop
sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Mitos.desktop

Building the Debian package

If the .deb file provided on the release page uses a libc version higher than that used by your Debian, Ubuntu, or Mint system, you can build the package from source to match your system’s dependencies.

Install cargo-deb, the tool used for building the .deb file:

cargo install cargo-deb

After cloning and entering the Mitos repository as previously described, use the following command to build the release binary and package it into a .deb file in a single step.

cargo deb -- --locked

💡 This locks you into the --release profile. But you can also build mitos in any way you like. As long as you leave a target/release/ms file, it will get packaged with cargo deb --no-build

💡 Don’t worry about the following:

warning: Failed to find dependency specification

Cargo deb just reports which packaged files it didn’t derive dependencies for. But so far the dependency deriving seams very good, even if some of the grammar files are skipped.

You can find the resulted .deb in target/debian/. It should contain everything it needs, including the

• completions for bash, fish, zsh
• .desktop file
• launcher to the binary with the runtime

Usage

For a full interactive introduction to Mitos, refer to the tutor which can be accessed via the command ms --tutor or :tutor.

💡 Currently, not all functionality is fully documented, please refer to the key mappings list.

Modes

Mitos is a modal editor, meaning it has different modes for different tasks. The main modes are:

• Normal mode: For navigation and editing commands. This is the default mode.
• Insert mode: For typing text directly into the document. Access by typing i in normal mode.
• Select/extend mode: For making selections and performing operations on them. Access by typing v in normal mode.

Buffers

Buffers are in-memory representations of files. You can have multiple buffers open at once. Use pickers or commands like :buffer-next and :buffer-previous to open buffers or switch between them.

Selection-first editing

Inspired by Kakoune, Mitos follows the selection → action model. This means that whatever you are going to act on (a word, a paragraph, a line, etc.) is selected first and the action itself (delete, change, yank, etc.) comes second. A cursor is simply a single width selection.

Multiple selections

Also inspired by Kakoune, multiple selections are a core mode of interaction in Mitos. For example, the standard way of replacing multiple instances of a word is to first select all instances (so there is one selection per instance) and then use the change action (c) to edit them all at the same time.

Motions

Motions are commands that move the cursor or modify selections. They’re used for navigation and text manipulation. Examples include w to move to the next word, or f to find a character. See the Movement section of the keymap for more motions.

Registers

• User-defined registers
• Default registers
• Special registers

In Mitos, registers are storage locations for text and other data, such as the result of a search. Registers can be used to cut, copy, and paste text, similar to the clipboard in other text editors. Usage is similar to Vim, with " being used to select a register.

User-defined registers

Mitos allows you to create your own named registers for storing text, for example:

• "ay - Yank the current selection to register a.
• "op - Paste the text in register o after the selection.

If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:

• "hc - Store the selection in register h and then change it (delete and enter insert mode).
• "md - Store the selection in register m and delete it.

Default registers

Commands that use registers, like yank (y), use a default register if none is specified. These registers are used as defaults:

Special registers

Some registers have special behavior when read from and written to.

When yanking multiple selections to the clipboard registers, the selections are joined with newlines. Pasting from these registers will paste multiple selections if the clipboard was last yanked to by the Mitos session. Otherwise the clipboard contents are pasted as one selection.

Surround

Mitos includes built-in functionality similar to vim-surround. The keymappings have been inspired from vim-sandwich:

You can use counts to act on outer pairs.

Surround can also act on multiple selections. For example, to change every occurrence of (use) to [use]:

1. % to select the whole file
2. s to split the selections on a search term
3. Input use and hit Enter
4. mr([ to replace the parentheses with square brackets

Multiple characters are currently not supported, but planned for future release.

Textobjects

Selecting and manipulating text with textobjects

In Mitos, textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code.

• ma - Select around the object (va in Vim, <alt-a> in Kakoune)
• mi - Select inside the object (vi in Vim, <alt-i> in Kakoune)

💡 f, t, etc. need a tree-sitter grammar active for the current document and a special tree-sitter query file to work properly. Only some grammars currently have the query file implemented. Contributions are welcome!

The s textobject uses spell-checking findings. Both mis and mas select the diagnosed word under the cursor; mIs and mAs select every finding fully contained in the current selection. Use [s and ]s to navigate to the previous or next finding. These commands also work in plain text and scratch buffers when spell checking is enabled.

Navigating using tree-sitter textobjects

Navigating between functions, classes, parameters, and other elements is possible using tree-sitter and textobject queries. For example to move to the next function use ]f, to move to previous type use [t, and so on.

For the full reference see the unimpaired section of the key bind documentation.

💡 This feature relies on tree-sitter textobjects and requires the corresponding query file to work properly.

Syntax-aware motions

Moving the selection with syntax-aware motions

Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls:

func(arg1, arg2, arg3);

A function call might be parsed by tree-sitter into a tree like the following.

(call
  function: (identifier) ; func
  arguments:
    (arguments           ; (arg1, arg2, arg3)
      (identifier)       ; arg1
      (identifier)       ; arg2
      (identifier)))     ; arg3

Use :tree-sitter-subtree to view the syntax tree of the main selection. In a more intuitive tree format:

            ┌────┐
            │call│
      ┌─────┴────┴─────┐
      │                │
┌─────▼────┐      ┌────▼────┐
│identifier│      │arguments│
│  "func"  │ ┌────┴───┬─────┴───┐
└──────────┘ │        │         │
             │        │         │
   ┌─────────▼┐  ┌────▼─────┐  ┌▼─────────┐
   │identifier│  │identifier│  │identifier│
   │  "arg1"  │  │  "arg2"  │  │  "arg3"  │
   └──────────┘  └──────────┘  └──────────┘

If you have a selection that wraps arg1 (see the tree above), and you use Alt-n, it will select the next sibling in the syntax tree: arg2.

// before
func([arg1], arg2, arg3)
// after
func(arg1, [arg2], arg3);

Similarly, Alt-o will expand the selection to the parent node, in this case, the arguments node.

func[(arg1, arg2, arg3)];

There is also some nuanced behavior that prevents you from getting stuck on a node with no sibling. When using Alt-p with a selection on arg1, the previous child node will be selected. In the event that arg1 does not have a previous sibling, the selection will move up the syntax tree and select the previous element. As a result, using Alt-p with a selection on arg1 will move the selection to the “func” identifier.

Pickers

Using pickers

Mitos has a variety of pickers, which are interactive windows used to select various kinds of items. These include a file picker, global search picker, and more. Most pickers are accessed via keybindings in space mode. Pickers have their own keymap for navigation.

Filtering Picker Results

Most pickers perform fuzzy matching using fzf syntax. Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the language server. Note that OR operations (|) are not currently supported.

If a picker shows multiple columns, you may apply the filter to a specific column by prefixing the column name with %. Column names can be shortened to any prefix, so %p, %pa or %pat all mean the same as %path. For example, a query of mitos %p .toml !lang in the global search picker searches for the term “mitos” within files with paths ending in “.toml” but not including “lang”.

You can insert the contents of a register using Ctrl-r followed by a register name. For example, one could insert the currently selected text using Ctrl-r-., or the directory of the current file using Ctrl-r-% followed by Ctrl-w to remove the last path section. The global search picker will use the contents of the search register if you press Enter without typing a filter. For example, pressing *-Space-/-Enter will start a global search for the currently selected text.

To keep navigating a picker’s current matched locations after closing it, press Ctrl-q to populate the quicklist.

File explorer

Space-e opens an interactive file explorer for browsing and opening files, rooted at the workspace; Space-. opens one rooted at the current buffer’s directory. Unlike the file picker, the explorer does not ignore most files by default; its ignore behaviour is configured separately in the [editor.file-explorer] section.

Supported images can be displayed in the preview pane. See Image previews for formats and rendering details.

Image previews

Mitos can preview PNG, JPEG, GIF, and WebP files directly in the terminal. Previews are read-only and fit the available pane. A caption shows the image format, dimensions in pixels, and file size.

Open an image

Open an image from your shell:

ms screenshot.png

Inside Mitos, use :open screenshot.png, the file picker (Space f), or the file explorer (Space e). The picker can also show an image in its preview pane before you open it.

Terminal rendering

Mitos detects the terminal’s image capabilities automatically. When detection fails, it falls back to rendering with half-block characters. The appearance and resolution therefore depend on your terminal.

Images resize to fit when the pane size changes. GIF and WebP previews show a still image; animation playback is not supported.

Preview limitations

Image previews do not provide image editing. Unsupported formats, files that cannot be decoded, or images that exceed the decoder’s limits show a binary-file placeholder instead.

The decoder limits image width and height to 32,768 pixels and its allocation budget to 128 MiB. A compressed file can be small on disk but still exceed the decoding budget. If a preview is unavailable, check the format and try a smaller copy of the image.

Quicklist

The quicklist keeps a picker’s matched file locations available after the picker closes. Unlike the jumplist, which records locations you leave, the quicklist is an explicit result set you can traverse in either direction.

Populating the quicklist

While a picker containing files or locations is open, press Ctrl-q to copy its current matched entries into the quicklist. The entries keep their current picker order, and the picker remains open. For example, you can filter global-search, diagnostics, or symbol results and capture only those matches.

The quicklist is editor-global and temporary. Capturing entries from another picker replaces its contents; capturing a picker with no matching locations clears it.

Navigating entries

The navigation commands accept a count, so 3]q jumps forward three entries. Quicklist jumps are added to the jumplist, allowing Ctrl-o to return to the location before the jump.

The quicklist picker shows every captured entry and marks the current one with *. Selecting an entry opens it and makes it the current quicklist position.

Typical workflow

1. Open a picker that shows file locations, such as global search, diagnostics, symbols, or another location-based picker.
2. Filter the picker until it contains the set of locations you want.
3. Press Ctrl-q to copy the current matched items into the quicklist.
4. Close the picker, then move through all collected locations with ]q and [q.
5. Use ]l and [l to restrict navigation to the current file, or Space-q to browse the complete list.

Jumplist

Using the jumplist

To help with quick navigation, Mitos maintains a list of “jumps” called the jumplist. Whenever you make a significant movement (see next section), Mitos stores your selections from before the move as a jump. A jump serves as a kind of checkpoint, allowing you to jump to a separate location, make edits, and return to where you were with your previous selections. This way, the jumplist tracks both your previous location and your selections. You can manually save a jump by using Ctrl-s. To jump backward in the jumplist, use Ctrl-o; to go forward, use Ctrl-i. To view and select from the full jumplist, use Space-j to open the jumplist picker.

If you want to keep a picker’s current matched locations as a separate navigation list, use the quicklist instead.

What makes a jump

The following is a non-exhaustive list of which actions add a jump to the jumplist:

• Switching buffers
  • Using the buffer picker, going to the next/previous buffer
  • Going to the last accessed/modified file
  • Making a new file (:new FILE)
  • Opening a file (:open FILE)
    • Includes :log-open, :config-open, :config-open-workspace, :tutor
  • Navigating by pickers, global search, or the file explorer
  • goto_file (gf)
• Big in-file movements
  • select_regex (s)
  • split_regex (S)
  • search (/)
  • keep_selections and remove_selections (K and <A-K>)
  • goto_file_start (gg)
  • goto_file_end
  • goto_last_line (ge)
  • :goto 123 / :123 / 123G
  • goto_definition (gd)
  • goto_declaration (gD)
  • goto_type_definition (gy)
  • goto_reference (gr)
• Other
  • Ctrl-s manually creates a jump
  • Trying to close a modified buffer can switch you to that buffer and create a jump
  • The debugger can create jumps as you jump stack frames

Keymap

• Normal mode
  • Movement
  • Changes
    • Shell
  • Selection manipulation
  • Search
  • Minor modes
    • View mode
    • Goto mode
    • Match mode
    • Window mode
    • Space mode
      • Popup
      • Completion Menu
      • Signature-help Popup
    • Unimpaired
• Insert mode
• Select / extend mode
• Picker
• Prompt

💡 Mappings marked (LSP) require an active language server for the file.

💡 Mappings marked (TS) require a tree-sitter grammar for the file type.

⚠️ Some terminals’ default key mappings conflict with Mitos’s. If any of the mappings described on this page do not work as expected, check your terminal’s mappings to ensure they do not conflict. See the wiki for known conflicts.

Normal mode

Normal mode is the default mode when you launch mitos. You can return to it from other modes by pressing the Escape key.

Movement

NOTE: Unlike Vim, f, F, t and T are not confined to the current line.

Hereafter, <n> represents an integer by typing a sequence of digits.

Changes

Shell

Selection manipulation

Search

Search commands all operate on the / register by default. To use a different register, use "<char>.

Minor modes

These sub-modes are accessible from normal mode and typically switch back to normal mode after a command.

These modes (except command mode) can be configured by remapping keys.

View mode

Accessed by typing z in normal mode.

View mode is intended for scrolling and manipulating the view without changing the selection. The “sticky” variant of this mode (accessed by typing Z in normal mode) is persistent and can be exited using the escape key. This is useful when you’re simply looking over text and not actively editing it.

Goto mode

Accessed by typing g in normal mode.

Jumps to various locations.

Match mode

Accessed by typing m in normal mode.

Please refer to the relevant sections for detailed explanations about surround and textobjects.

Window mode

Accessed by typing Ctrl-w in normal mode.

This layer is similar to Vim keybindings as Kakoune does not support windows.

Space mode

Accessed by typing Space in normal mode.

This layer is a kludge of mappings, mostly pickers.

💡 Global search displays results in a fuzzy picker, use Space + ' to bring it back up after opening a file.

Popup

Displays documentation for item under cursor. Remapping currently not supported.

Completion Menu

Displays documentation for the selected completion item. Remapping currently not supported.

Any other keypresses result in the completion being accepted.

Signature-help Popup

Displays the signature of the selected completion item. Remapping currently not supported.

Unimpaired

These mappings are in the style of vim-unimpaired.

Insert mode

Accessed by typing i in normal mode.

Insert mode bindings are minimal by default. Mitos is designed to be a modal editor, and this is reflected in the user experience and internal mechanics. Changes to the text are only saved for undos when escaping from insert mode to normal mode.

💡 New users are strongly encouraged to learn the modal editing paradigm to get the smoothest experience.

These keys are not recommended, but are included for new users less familiar with modal editors.

As you become more comfortable with modal editing, you may want to disable some insert mode bindings. You can do this by editing your config.toml file.

[keys.insert]
up = "no_op"
down = "no_op"
left = "no_op"
right = "no_op"
pageup = "no_op"
pagedown = "no_op"
home = "no_op"
end = "no_op"

Select / extend mode

Accessed by typing v in normal mode.

Select mode echoes Normal mode, but changes any movements to extend selections rather than replace them. Goto motions are also changed to extend, so that vgl, for example, extends the selection to the end of the line.

Search is also affected. By default, n and N will remove the current selection and select the next instance of the search term. Toggling this mode before pressing n or N makes it possible to keep the current selection. Toggling it on and off during your iterative searching allows you to selectively add search terms to your selections.

Picker

Keys to use within picker. Remapping currently not supported. See the documentation page on pickers for more info. Prompt keybinds also work in pickers, except where they conflict with picker keybinds.

Prompt

Keys to use within prompt, Remapping currently not supported.

Command line

• Quoting
• Flags
• Expansions
• Exceptions

The command line is used for executing typable commands like :write or :quit. Press : to activate the command line.

Typable commands optionally accept arguments. :write for example accepts an optional path to write the file contents. The command line also supports a quoting syntax for arguments, flags to modify command behaviors, and expansions - a way to insert values from the editor. Most commands support these features but some have custom parsing rules (see the exceptions below).

Quoting

By default, command arguments are split on tabs and space characters. :open README.md CHANGELOG.md for example should open two files, README.md and CHANGELOG.md. Arguments that contain spaces can be surrounded in single quotes (') or backticks (`) to prevent the space from separating the argument, like :open 'a b.txt'.

Double quotes may be used the same way, but double quotes expand their inner content. :echo "%{cursor_line}" for example may print 1 because of the expansion for the cursor_line variable. :echo '%{cursor_line}' though prints %{cursor_line} literally: content within single quotes or backticks is interpreted as-is.

On Unix systems the backslash character may be used to escape certain characters depending on where it is used. Within an argument which isn’t surround in quotes, the backslash can be used to escape the space or tab characters: :open a\ b.txt is equivalent to :open 'a b.txt'. The backslash may also be used to escape quote characters (', `, ") or the percent token (%) when used at the beginning of an argument. :echo \%sh{foo} for example prints %sh{foo} instead of invoking a foo shell command and :echo \"quote prints "quote. The backslash character is treated literally in any other situation on Unix systems and always on Windows: :echo \n always prints \n.

Flags

Command flags are optional switches that can be used to alter the behavior of a command. For example the :sort command accepts an optional --reverse (or -r for short) flag which causes the sort command to reverse the sorting direction. Typing the - character shows completions for the current command’s flags, if any.

The -- flag specifies the end of flags. All arguments after -- are treated as positional arguments: :open -- -a.txt opens a file called -a.txt.

Expansions

Expansions are patterns that Mitos recognizes and replaces within the command line. Mitos recognizes anything starting with a percent token (%) as an expansion, for example %sh{echo hi!}. Expansions are particularly useful when used in commands like :echo or :noop for executing simple scripts. For example:

[keys.normal]
# Show the current Git branch in the status area.
F12 = ":echo %sh{git branch --show-current}"

Expansions take the form %[<kind>]<open><contents><close>. In %sh{echo hi!}, for example, the kind is sh - the shell expansion - and the contents are “echo hi!”, with { and } acting as opening and closing delimiters. The following open/close characters are recognized as expansion delimiter pairs: (/), [/], {/} and </>. Plus the single characters ', " or | may be used instead: %{cursor_line} is equivalent to %<cursor_line>, %[cursor_line] or %|cursor_line|.

To escape a percent character instead of treating it as an expansion, use two percent characters consecutively. To execute a shell command like date -u +'%Y-%m-%d', double the percent characters: :echo %sh{date -u +'%%Y-%%m-%%d'}.

When no <kind> is provided, Mitos will expand a variable. For example %{cursor_line} can be used as in argument to insert the line number. :echo %{cursor_line} for instance may print 1 to the statusline.

The following variables are supported:

Aside from editor variables, the following expansions may be used:

• Unicode %u{..}. The contents may contain up to six hexadecimal numbers corresponding to a Unicode codepoint value. For example :echo %u{25CF} prints ● to the statusline.
• Shell %sh{..}. The contents are passed to the configured shell command. For example :echo %sh{echo "20 * 5" | bc} may print 100 on the statusline on when using a shell with echo and the bc calculator installed. Shell expansions are evaluated recursively. %sh{echo '%{buffer_name}:%{cursor_line}'} for example executes a command like echo 'README.md:1': the variables within the %sh{..} expansion are evaluated before executing the shell command.
• Register %reg{..}. The contents should be a single character representing the register name. For example, :set-register a hello world followed by echo %reg{a} prints hello world to the statusline.
• Positional argument %arg{..}. Within a custom command, the contents are a zero-based argument index. For example, %arg{0} expands to the first argument passed to the custom command. Missing arguments expand to an empty string.

As mentioned above, double quotes can be used to surround arguments containing spaces but also support expansions within the quoted content unlike single quotes or backticks. For example :echo "circle: %u{25CF}" prints circle: ● to the statusline while :echo 'circle: %u{25CF}' prints circle: %u{25CF}.

Note that expansions are only evaluated once the Enter key is pressed in command mode.

Exceptions

The following commands support expansions but otherwise pass the given argument directly to the shell program without interpreting quotes:

• :insert-output
• :append-output
• :pipe
• :pipe-to
• :run-shell-command

For example executing :sh echo "%{buffer_name}:%{cursor_column}" would pass text like echo "README.md:1" as an argument to the shell program: the expansions are evaluated but not the quotes. As mentioned above, percent characters can be used in shell commands by doubling the percent character. To insert the output of a command like date -u +'%Y-%m-%d' use :insert-output date -u +'%%Y-%%m-%%d'.

The :set-option and :toggle-option commands use regular parsing for the first argument - the config option name - and parse the rest depending on the config option’s type. :set-option interprets the second argument as a string for string config options and parses everything else as JSON.

:toggle-option’s behavior depends on the JSON type of the config option supplied as the first argument:

• Booleans: only the config option name should be provided. For example :toggle-option format.on-save will flip the format.on-save option.
• Strings: the rest of the command line is parsed with regular quoting rules. For example :toggle-option indent-heuristic hybrid tree-sitter simple cycles through “hybrid”, “tree-sitter” and “simple” values on each invocation of the command.
• Numbers, arrays and objects: the rest of the command line is parsed as a stream of JSON values. For example :toggle-option rulers [81] [51, 73] cycles through [81] and [51, 73].

When providing multiple values to :toggle-option there should be no duplicates. :toggle-option indent-heuristic hybrid simple tree-sitter simple for example would only toggle between “hybrid” and “tree-sitter” values.

:lsp-workspace-command works similarly to :toggle-option. The first argument (if present) is parsed according to normal rules. The rest of the line is parsed as JSON values. Unlike :toggle-option, string arguments for a command must be quoted. For example :lsp-workspace-command lsp.Command "foo" "bar".

Commands

• Typable commands
• Static commands

Typable commands

Typable commands are used from command mode and may take arguments. Command mode can be activated by pressing :. The built-in typable commands are:

Static Commands

Static commands take no arguments and can be bound to keys. Static commands can also be executed from the command picker (<space>?). The built-in static commands are:

Language servers

Mitos has built-in support for the Language Server Protocol, providing IDE-like features — diagnostics, completion, goto-definition, rename and more, for any language that has a server configured. Language servers are separate programs you install yourself: the language support page lists which languages ship with a server configured, and the language server configuration wiki has per-server installation notes.

Run ms --health <language> to check whether Mitos found the configured server for a language. After changing a server’s configuration, :lsp-restart reloads it and :lsp-stop stops it; :lsp-workspace-command runs a command the server exposes for the workspace.

Features

Most features are bound by default (see the keymap); the relevant keys are listed below.

Configuration

The [editor.lsp] section of config.toml groups LSP behaviour into feature subsections, including inlay-hints.enable, signature-help.auto-trigger, document-highlight.auto-trigger, and completion.snippets. Set enable = false to disable LSP entirely. How much diagnostic detail is shown inline at the cursor is configured separately in [editor.diagnostics.inline].

Which server(s) a language uses, the server’s command and arguments, and any language-specific settings are configured in languages.toml (see Language Server configuration). A language may use several servers: for each request the first server in the list that supports it is used, and a server’s features can be limited with only-features / except-features.

Debugging (DAP)

Mitos has experimental support for the Debug Adapter Protocol (DAP) for setting breakpoints, stepping through code, and inspecting variables. Install a debug adapter separately and configure it for the language you want to debug.

Configure an adapter

Debug adapters are configured per language in languages.toml. Some languages already have an adapter and launch templates configured. For example, Rust uses lldb-dap by default; its executable must be available on PATH.

To configure or override an adapter, add a language entry to your user languages.toml. This example matches the built-in Rust binary template:

[[language]]
name = "rust"

[language.debugger]
name = "lldb-dap"
transport = "stdio"
command = "lldb-dap"

[[language.debugger.templates]]
name = "binary"
request = "launch"
completion = [{ name = "binary", completion = "filename" }]
args = { program = "{0}" }

Each template defines a launch or attach request and adapter-specific arguments. completion defines the input prompts; {0}, {1}, and so on are replaced with the supplied values. Mitos sets the debug target’s cwd to the editor’s current working directory.

See the debugger configuration reference for TCP transport, attach templates, and the complete list of fields. Project-local configuration in .mitos/languages.toml is subject to workspace trust.

Start a session

1. Build the program you want to debug, with debug information enabled.
2. Open a source file in Mitos. Its language determines which adapter and templates are used.
3. Press Space G b on a line to toggle a breakpoint.
4. Press Space G l, choose a template, and fill in its prompts.
5. When execution pauses, step through the code or inspect variables using the commands below.

G is uppercase. Press the keys in sequence. The debug menu stays active after a command; while it is active, use the suffix keys such as n or c directly. Press Esc to leave the menu.

You can also start a template from the command line. For a Rust binary built with cargo build, for example:

:debug-start binary target/debug/my-program

Replace my-program with your executable’s name. To connect to an already running TCP debug adapter, use :debug-remote <ip>:<port> <template> [parameters...], for example :debug-remote 127.0.0.1:4711 binary target/debug/my-program.

Debugging commands

These bindings are available in normal and select mode:

Use :debug-eval <expression> to evaluate an expression in the current debug context. Supported expressions and debugging capabilities depend on the adapter.

Troubleshooting

• No debug adapter available for language: check the current file’s language and its [language.debugger] configuration.
• Failed to start debug client: check the adapter’s executable path, arguments, and transport.
• No debug config with given name: use a template name defined in [[language.debugger.templates]].
• Workspace is not trusted: use :workspace-trust to allow debugging in a workspace you trust. See workspace trust.

Spell checking

Mitos can spell-check documents and surface misspellings as diagnostics. Corrections and “add to dictionary” are offered as code actions, alongside any from language servers.

Spell checking is opt-in. Mitos will use tree-sitter to check only requested regions of a language to avoid noisy diagnostics for keywords. Multiple dictionaries may be configured at once. A word is accepted if any configured dictionary allows it.

Enabling

There are several ways to turn spell checking on:

1. Per buffer, with the command:

   :set-spelling-language <language>
   

   Pass several languages to check against all of them (:set-spelling-language en_US en_GB), or off to disable checking for the buffer. With no argument it reports the current language(s). This choice overrides the settings below and persists across config reloads for that buffer.

2. Per path, with an .editorconfig spelling_language key:

   [*.md]
   spelling_language = en_US
   

3. Per language, in languages.toml (see Languages):

   [[language]]
   name = "markdown"
   spelling.languages = ["en_US"]
   

4. Globally, in config.toml under [editor.spelling]:

   [editor.spelling]
   languages = ["en_US"]
   

Scope

What gets checked is controlled per language by a tree-sitter spellcheck.scm query: a node captured @spell is checked, and @nospell excludes part of one. Most languages inject a shared comment grammar, so their comments are checked with no language-specific query. The bundled queries also cover:

Python docstrings are treated as prose; examples and markup inside them are not parsed separately. reStructuredText directive bodies are left unchecked because their syntax nodes do not distinguish prose from code.

Coverage depends on the queries present in your runtime directories. Strings and identifiers are checked only where a language’s query opts them in. With syntax parsing, text outside @spell captures is left unchecked. Plain text and files without a syntax tree are checked in full.

See Adding spellcheck queries to extend coverage to a new language.

Navigating and selecting findings

Use ]s to select the next spelling finding and [s to select the previous one. These commands skip other diagnostics, support counts such as 3]s, and stop at the first or last finding without wrapping. In select mode they extend the selection; with multiple cursors each cursor moves independently.

The s textobject selects the diagnosed word under the cursor with mis or mas. Use mIs or mAs to select all spelling findings fully contained in the current selection. Both inside and around variants use the finding’s exact range.

Correcting findings

Move onto a misspelled word (or select it with ]s, [s, or mis) and press Space-a to open code actions. Choose a Replace ... action and press Enter to replace the whole word. Press u to undo the correction, or Escape to dismiss the menu without changing the text.

Spelling actions work without a language server. With multiple selections, the menu offers corrections for findings overlapping the primary selection. The same menu offers Add ... to dictionary to accept a word permanently.

Ignoring a word for this session

Choose Ignore 'word' for this session (language) from Space-a to suppress that word until Mitos exits. Matching is case-insensitive and applies to the whole word, including in other open buffers and buffers opened later that use the chosen dictionary. Other misspellings continue to be checked.

With multiple dictionaries, choose the language the ignore should apply to. A buffer ignores the word if any of its configured dictionaries has a session ignore for it. The ignore survives edits, configuration reloads, and toggling spell checking off and back on. It does not change the document or write to your personal dictionary or configuration files.

Ignoring a word permanently

Choose Ignore 'word' forever (language) from Space-a to keep ignoring it after restarting Mitos, across projects using that dictionary. Matching is case-insensitive and applies to the whole word, just like a session ignore.

Persistent ignores are stored as UTF-8 text, one word per line, in <config>/spelling/<language>.ignore, for example ~/.config/mitos/spelling/en_US.ignore on Linux. They are loaded when the dictionary is first used. Remove a word from that file and restart Mitos to check it again, or add words there by hand.

Ignore forever suppresses findings without adding words to the dictionary’s suggestion vocabulary. Use Add ... to dictionary when you also want the word available as a correction suggestion. A failed save reports an error and leaves the word’s checking behavior unchanged.

Dictionaries

Dictionaries are Hunspell .aff/.dic pairs loaded from dictionaries/<language>/<language>.{aff,dic} in the runtime directories. ms --health lists those directories.

Mitos bundles only en_US. To add another language, drop its Hunspell files into a runtime directory, named after the language code you reference in the config. For example, for de_DE:

~/.config/mitos/runtime/dictionaries/de_DE/de_DE.aff
~/.config/mitos/runtime/dictionaries/de_DE/de_DE.dic

Hunspell dictionaries for most languages are distributed with LibreOffice and by the various aspell/Hunspell projects.

Personal dictionary

The “Add to dictionary” code action accepts a word permanently. It is appended to a personal dictionary, one word per line, under Mitos’s state directory:

<state>/dictionaries/<language>.txt

(<state> is e.g. ~/.local/state/mitos on Linux.) The file is namespaced per language, so a word added for one language is not accepted in another. You can edit it by hand; entries are loaded the next time that language’s dictionary is read.

Tuning

Spell checking produces false positives on names, jargon, and code-like tokens. URLs and email addresses are skipped automatically. Beyond that, three knobs (settable globally under [editor.spelling] and per language in languages.toml) reduce noise:

When both global and per-language settings are present, languages and min-word-length are replaced by the language’s value, while words and ignore-regexes are added to the global lists. See [editor.spelling] for the full reference.

Language support

The following languages and Language Servers are supported. To use Language Server features, you must first configure the appropriate Language Server.

You can check the language support in your installed Mitos version with ms --health.

Also see the Language Configuration docs and the Adding Languages guide for more language configuration information.