Documentation
Introduction
For scripting functions and plugin development, see the API Reference.
Koi Editor is configured using a single human-readable configuration file.
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 ⌘ command + , or from the Command Palette.
A copy of the latest default configuration is always available from the Koi repository.
Config file structure
The config file is divided into sections:
-- this is a comment
[license]
...
[editor]
...
[models]
...
[keybinds]
...
[user]
...
[theme-name*]
Sections can be removed or commented out if not needed.
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/koi-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 in spaces. |
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. |
Example using adaptive theme
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]
[monokai]
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
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_symbol |
Prefix used to identify inline shell commands. Default: %. |
inline_chat_symbol |
Prefix used to identify inline chat prompts. Default: >. |
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_symbol %
inline_chat_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_symbol:
% pwd
Run the command with Inline command.
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())
Evaluate the expression with Inline command.
Inline chat
Inline chat prompts use the configured inline_chat_symbol.
With the default configuration:
> Explain why this function may be slow.
Place the cursor on the prompt line and submit with Inline command.
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. |
show_splitter_handle |
Show the handle between split editor panes. |
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. Default: 530. |
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. This is currently disabled. |
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 |
|---|---|
whitespace_symbol |
Character used for visible whitespace. |
bookmark_prefix |
Prefix used to identify bookmarks. Default: !>. This is currently disabled. |
annotation_words |
Comma-separated words recognized as annotations by the navigator panel. |
vertical_rulers |
Comma-separated list of columns at which to draw vertical rulers. |
Example
whitespace_symbol ▪
-- bookmark_prefix !>
annotation_words TODO, NOTE, MARK, FIXME
vertical_rulers 80, 120
Experimental
Several settings are available but are experimental, unused, or retained for development:
-- always_show_completion_list true
-- wrap_word txt, md,
-- use_native_title_bar false
-- dim_non_active_editors false
-- fixed_line_number_width false
-- path_to_shell /bin/zsh
Models
Koi supports AI models through Ollama.
Example
[models]
code_completion qwen2.5-coder:1.5b
inline_chat gpt-oss:120b-cloud
- The
code_completionsetting is used for inline code suggestions and works best with fill-in-the-middle (FIM) models. - The
inline_chatsetting is used by the inline chat command.
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 bindings can be assigned to the same command by separating them with commas:
undo Cmd + Z, Control + /
Multiple 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.
All active key bindings are listed in the Command Palette.
Common navigation commands include:
show_file_explorer Cmd + P
show_outline_panel Cmd + I
show_buffer_explorer Cmd + B, Cmd + Shift + \
show_command_palette Cmd + Shift + P
go_to_line Cmd + G
open_terminal Cmd + T
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
The detect_tab_width command examines the current document and automatically determines the likely indentation width and whether the file primarily uses tabs or 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
- The
eol_mode_*commands change the EOL mode for the current buffer. - The
replace_all_eolcommand converts existing line endings in the current document to the active EOL mode.
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 are
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
The extend_to_buffer_* commands are available for extending the active tab selection.
Previous and next buffers can be selected with:
previous_tab Cmd + ;, Option + Cmd + Left
next_tab Cmd + ', Option + Cmd + Right
previous_tab_extend Cmd + Shift + ;, Option + Shift + Cmd + Left
next_tab_extend Cmd + Shift + ', Option + Shift + Cmd + Right
Pane navigation commands are available separately:
focus_main_editor
focus_split_editor
They do not have default key bindings.
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.
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 |
Links in Markdown and Org. Falls back to special. |
_bold |
Bold rich-text syntax. Falls back to builtin. |
_italic |
Italic rich-text syntax. Falls back to name. |
_underline |
Underlined rich-text syntax. Falls back to default. |
_verbatim |
Verbatim rich-text syntax. Falls back to name. |
_strike |
+Strikethrough rich-text syntax.+ Falls back to comment. |
_code |
Inline code in Markdown and Org. Falls back to comment. |
_todo |
TODO syntax. Falls back to the cursor color. This is currently disabled. |
_annotation |
Editor annotations. Falls back to comment. |
_error |
Errors and deleted diff lines. |
_warning |
Warnings, including status bar 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 config
[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
file_explorer_root
file_types_to_exclude .dmg, .app, .git, .ttf, .dylib, .so, .venv, .pyc, .zip, .egg, .DS_Store, dist, build
inline_command_in_files txt, md, org,
inline_shell_symbol %
inline_chat_symbol >
annotation_words TODO, NOTE, MARK, FIXME
scripts_enabled false
allow_unsafe_scripts false
click_on_links false
accept_auto_completion
accept_code_completion
show_line_numbers true
show_scrollbar true
show_minimap false
show_indent_guides true
show_annotations true
show_ui_borders false
show_splitter_handle false
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
show_line_info true
show_file_explorer_root true
show_file_with_path false
show_model_info true
show_active_lexer true
ui_font SF Mono
scrollbar_width 4
minimap_width 64
open_on_largest_screen true
eol_mode lf
eol_symbols_visible false
window_opacity 1
selection_opacity 0.2
indent_guides_opacity 0.1
whitespace_opacity 0.1
whitespace_symbol ▪
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
show_file_explorer Cmd + P
show_outline_panel Cmd + I
show_buffer_explorer Cmd + B, Cmd + Shift + \
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
Most settings can be changed immediately. Settings marked as requiring a restart take effect after the next relaunch.
API Reference
Default config-file