Last updated: Aug 17, 2026

For scripting functions and plugin development, see the API Reference.

Documentation

Koi Editor is configured using a single human-readable configuration file.

Contents

The configuration format is designed to be simple to edit, version control, and share. Most settings can be changed without restarting the editor unless otherwise noted.

Open the configuration file at any time with Cmd + , or from the Command Palette.

Config file structure

The config file is divided into sections:

[license]
[editor]
[models]
[keybinds]
[user]

[theme-name*]

Sections can be omitted if they are not needed. Comments begin with --.

License

[license]

path_to_license_file
Setting Description
path_to_license_file Absolute path to your Koi license file.

Example:

path_to_license_file            /Users/michael/Desktop/license.json

Editor

Appearance

Setting Description
font Editor font. Use any installed font or place a font in Application Support/Koi/fonts.
font_weight light, normal, medium, bold. Leave empty to use the default: normal in light mode and light in dark mode.
font_size Font size in points.
line_extra_height Additional spacing between lines.
tab_width Display width of a tab.
theme Active color theme. Set to adaptive to follow the system appearance.
adaptive_theme Light and dark theme pair used when theme is set to adaptive. 
theme                           adaptive
adaptive_theme                  koi, koi-dark

Built-in themes include:

[koi]
[koi-dark]
[koi-mono]
[hackerman]
[focus]
[writer]
[github-dark]
[kujukuju]
[ayu-dark]
[chatgpt]
[dracula]
[gruvbox]
[jblow]
[mono-light]
[tokyo-night]
[catppuccin]
[nord]

See Themes for more on how to customize themes.

Editing

Setting Description
auto_indent Automatically indent new lines.
auto_complete Enable context-aware auto completion.
tabs_over_spaces Prefer tabs instead of spaces for indentation.
font_ligatures Enable font ligatures. Requires restart.

Auto completion uses the contents of the current document as context. It suggests words, names, and symbols that already appear in the open file.

Project-wide completion is currently not supported.

Completion

Auto completion and AI code completion can be accepted independently using editor commands.

Setting Description
accept_auto_completion Editor command that accepts the current auto-completion suggestion. Default: newline.
accept_code_completion Editor command that accepts the current AI code-completion suggestion. Default: tab.

These settings are additive: the selected editor command keeps its normal behavior when there is no completion to accept.

accept_auto_completion          newline
accept_code_completion          tab

With this configuration, Return accepts an active auto-completion suggestion before inserting a newline, while Tab accepts an active code-completion suggestion before inserting indentation.

Files

Setting Description
file_explorer_root Absolute path to the folder used as the file explorer root on startup. Defaults to the Desktop.
file_types_to_exclude Comma-separated files, extensions, and directories excluded from the file explorer and file index.
files_to_open_on_startup Comma-separated list of absolute paths to files opened when Koi launches.
path_to_scripts_file Path to an external scripts file. Requires restart.

Example exclusions:

file_types_to_exclude           .dmg, .app, .git, .ttf, .dylib, .so, .venv, .pyc, .zip, .egg, .DS_Store, dist, build

Koi does not use project files or project-specific configuration. Any folder can be selected as the file explorer root, allowing it to act as the working scope for a repository, project, collection of notes, or any other directory.

The file explorer can also be used as a general-purpose file browser. Resetting the root with Reset file explorer command returns it to the default location.

Inline Commands

Setting Description
inline_command_in_files File types supporting inline commands.
inline_shell_start_symbol Prefix used to identify shell commands.
scripts_enabled Enable scripting support.
+allow_unsafe_scripts+ +Allow imports and other unsafe script functionality.+ This is currently disabled.
click_on_links Open links directly when enabled. When disabled, links can be activated through Inline command.

Example:

inline_command_in_files         txt, md, org,
inline_shell_start_symbol       %

scripts_enabled                 false
allow_unsafe_scripts            false

click_on_links                  false

Inline command allow shell commands, expressions, and AI chat to be executed directly from a document.

Shell commands

A shell command begins with the configured inline_shell_start_symbol:

% pwd

Run the command using the inline_command key binding:

Cmd + Shift + Return

Inline shell commands have a hard execution timeout of 10 seconds. They are intended for short, one-off commands and scripts rather than interactive programs, long-running processes, or REPL sessions.

Python expressions

Python expressions can also be evaluated inline:

print("hello there")

For example, to print the current date without importing additional modules:

print(__import__("datetime").date.today())

Run the expression using:

Cmd + Shift + Return

Inline chat

Any line in a supported document can be used as an inline chat prompt.

Explain why this function may be slow.

Place the cursor on the prompt line and run:

Cmd + K

The configured inline chat model uses the current file as context and writes the response directly into the document.

Configure the model in [models]:

[models]

inline_chat                     gpt-oss:120b-cloud

User Interface

Setting Description
show_line_numbers Show line numbers.
show_scrollbar Show the editor scrollbar.
show_minimap Show the minimap.
show_indent_guides Show indentation guides.
show_annotations Show editor annotations.
+show_ui_borders+ +Draw borders around editor UI components.+ This will likely be removed.

Cursor

Setting Description
cursor_width Caret width in pixels.
cursor_extra_height Additional cursor height.
cursor_as_block Display the caret as a block cursor.
cursor_line_highlight Highlight the current line.
cursor_blink Enable cursor blinking.
cursor_blink_period Cursor blink interval in milliseconds. 530 is the default.
cursor_trail_effect Show a short animated trail when the cursor moves.

Example:

cursor_width                    2
cursor_extra_height             8

cursor_as_block                 false
cursor_line_highlight           true

cursor_blink                    false
cursor_blink_period             530

cursor_trail_effect             false

Status Bar

Setting Description
show_line_info Display the current line and column.
show_word_count Display document word and character count. This is automatically disabled on larger files.
show_file_explorer_root Display the current file explorer root.
show_file_with_path Display the full path of the active file.
show_model_info Display the active AI models.
show_active_lexer Display the active syntax lexer.

Fonts

Setting Description
ui_font Font used by the editor UI.
ui_font_weight UI font weight. Leave empty for the default.
ui_font_size UI font size. Leave empty for the default.

Layout

Setting Description
scrollbar_width Scrollbar width.
minimap_width Minimap width.
open_on_largest_screen Open Koi on the largest connected display.

Line Endings

Setting Description
eol_mode Default EOL mode: lf, crlf, or cr.
eol_symbols_visible Show end-of-line symbols.

Example:

eol_mode                        lf
eol_symbols_visible             false

The EOL mode can also be changed for the current buffer from the Command Palette. Koi provides commands for changing the active EOL mode and for converting all existing line endings in a document.

Terminal

Setting Description
terminal_to_use Preferred terminal application. Leave empty to use Apple Terminal.

Visual Opacity

Setting Description
window_opacity Window opacity.
selection_opacity Selection background opacity.
indent_guides_opacity Indentation guide opacity.
whitespace_opacity Whitespace marker opacity.

Example:

window_opacity                  1
selection_opacity               0.2
indent_guides_opacity           0.1
whitespace_opacity              0.1

Symbols and rulers

Setting Description
+unsaved_symbol+ +Custom marker for modified files.+ Currently not in use.
whitespace_symbol Character used for visible whitespace.
vertical_rulers Comma-separated list of columns at which to draw vertical rulers. 
whitespace_symbol               ▪
vertical_rulers                 80, 120

Experimental

Several settings are available but are still considered experimental or already removed:

-- always_show_completion_list         true
-- wrap_word                           txt, md,
-- use_native_title_bar                false
-- dim_non_active_editors              false
-- fixed_line_number_width             false

Models

Koi supports AI models through Ollama.

Example:

[models]

code_completion                 qwen2.5-coder:1.5b
inline_chat                     gpt-oss:120b-cloud

Both settings are optional. Koi can be used without configuring AI models.

Key Bindings

Keyboard shortcuts are configured in the [keybinds] section.

Example:

save_file                       Cmd + S
find_in_file                    Cmd + F
duplicate_line                  Cmd + Shift + D

Multiple shortcuts can be assigned to the same command by separating them with commas:

undo                            Cmd + Z, Control + /

Bindings are additive and can be customized independently.

Use the names Comma, Period, Plus, and Minus when binding those punctuation keys.

open_config_file                Cmd + Comma
document_start                  Option + Comma
document_end                    Option + Period

Unassigned commands can simply be left blank.

Koi includes commands for file management, navigation, selection, multi-cursor editing, indentation, line endings, search, diffing, editor layout, and other operations.

The Command Palette (Cmd + Shift + P by default, or always available on Right-Click) provides access to commands without requiring a keyboard shortcut.

Indentation

Indentation can be controlled independently for each buffer using commands including:

detect_tab_width
tab_width_2_spaces
tab_width_4_spaces
tab_width_8_spaces

indent_with_spaces
indent_with_tabs

replace_tabs_with_spaces

This makes it possible to open files with different indentation conventions without changing the global tab_width setting.

Line endings

Koi provides commands for inspecting and changing line endings:

toggle_eol_symbols
replace_all_eol

eol_mode_lf
eol_mode_crlf
eol_mode_cr

Multi-cursor and selection

Koi includes commands for creating and manipulating multiple selections:

select_next_match
unselect_last_match
select_matches

line_add_caret_up
line_add_caret_down

add_cursors_to_line_starts

For example, the default bindings include:

select_next_match               Cmd + E
unselect_last_match             Cmd + Shift + E
select_matches                  Cmd + Option + F

line_add_caret_up               Control + Shift + Up
line_add_caret_down             Control + Shift + Down

Buffer navigation

Buffers can be selected directly with:

switch_to_buffer_1              Cmd + 1
switch_to_buffer_2              Cmd + 2
...
switch_to_buffer_9              Cmd + 9

Equivalent extend_to_buffer_* commands are available for extending the active tab selection.

Pane navigation is configured separately:

focus_main_editor               Control + Left
focus_split_editor              Control + Right

User Commands

The [user] section is reserved for your own editor commands.

Example:

[user]

word_count
insert_uuid
insert_link
insert_unchecked_box
fenced_block
make_bold

Custom functions can then be assigned keyboard shortcuts like built-in commands.

User commands also appear in the Command Palette.

For scripting functions and plugin development, see the API Reference.

Language-specific configuration

This is still under development.

Themes

Themes are named sections in the configuration file.

Example:

[koi-dark]

background                      #212529
foreground                      #FFFFFF
cursor                          #C6E5FF

keyword                         #E67D74
string                          #D4BC7D
comment                         #87919D
...

Each theme consists of a collection of named styles.

Core colors

Style Description
background Editor background.
foreground UI foreground color.
text_color Highlighted or selected text items in UI.
cursor Caret color.

Syntax colors

Style Description
default Default text.
keyword Language keywords.
class Class names.
name Function names.
lambda Anonymous functions.
string String literals.
number Numbers.
operator Operators.
comment Comments.
special Language-specific symbols.
type Types.
constant Constants.
builtin Built-in functions.

Optional styles

These styles fall back to sensible defaults if omitted.

Style Description
_selection Selection color.
_highlight Search highlights.
_link Hyperlinks.
_bold Bold text.
_italic Italic text.
_underline Underlined text.
_verbatim Verbatim text.
_strike Strikethrough text (this is currently not supported).
_code Inline code.
_todo TODO items (this is currently not supported).
_annotation Editor annotations.
_error Errors and deleted diff lines.
_warning Warnings and modified diff lines.
_success Success indicators and added diff lines.

Style format

A style may contain only a foreground color:

keyword                         #FF79C6

A foreground color and modifier:

keyword                         #FF79C6, bold

A foreground and background color:

_link                           #0081FF, #0081FF

Foreground and background can use the same color. Koi applies opacity to the background.

Or a foreground, background, and modifier:

keyword                         #FF79C6, #282A36, italic

Supported modifiers are bold and italic.

Example

[editor]

font                            SF Mono
font_size                       15

line_extra_height               2
tab_width                       4

theme                           adaptive
adaptive_theme                  koi, koi-dark

auto_indent                     true
auto_complete                   true

accept_auto_completion          newline
accept_code_completion          tab

show_line_numbers               true
show_scrollbar                  true
show_minimap                    false
show_indent_guides              true

cursor_width                    2
cursor_extra_height             8
cursor_line_highlight           true
cursor_trail_effect             false

show_line_info                  true
show_word_count                 false
show_active_lexer               true

eol_mode                        lf
eol_symbols_visible             false

tabs_over_spaces                false
font_ligatures                  false

[models]

-- code_completion              qwen2.5-coder:1.5b
-- inline_chat                  gpt-oss:120b-cloud

[keybinds]

open_config_file                Cmd + Comma
show_command_palette            Cmd + Shift + P

find_in_file                    Cmd + F
show_search_explorer            Cmd + Shift + F

select_next_match               Cmd + E
unselect_last_match             Cmd + Shift + E
select_matches                  Cmd + Option + F

inline_command                  Cmd + Shift + Return
submit_prompt                   Cmd + K

Most settings can be changed immediately. Settings marked as requiring a restart take effect after the next relaunch.