# Documentation

---

## Introduction

> For scripting functions and plugin development, see the [API Reference](/api/index.html).

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 <span class="badge badge-small">⌘ command</span> + <span class="badge badge-small">,</span> or from the <span class="badge badge-small">Command Palette</span>.

A copy of the latest default configuration is always available from the [Koi repository](https://github.com/hackermanai/koi/blob/main/.hackerman).

## Config file structure

The config file is divided into sections:

```ini
-- this is a comment

[license]
...

[editor]
...

[models]
...

[keybinds]
...

[user]
...

[theme-name*]
```

Sections can be removed or commented out if not needed.

## License

```ini
[license]

path_to_license_file
```

| Setting | Description |
|---------|-------------|
| `path_to_license_file` | Absolute path to your Koi license file. |

{ .text-center .muted }
Example

```ini
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`. |

{ .text-center .muted }
Example using `adaptive` theme

```ini
theme                           adaptive
adaptive_theme                  koi, koi-dark
```

Built-in themes include:

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

{ .text-center .muted }
See [Themes](#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.

```ini
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.** |

{ .text-center .muted }
Example
    
```ini
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 <span class="badge badge-small">Reset file explorer</span> 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 <span class="badge badge-small">Inline command</span>. |

{ .text-center .muted }
Example

```ini
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`:

```bash
% pwd
```

Run the command with <span class="badge badge-small">Inline command</span>.

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:
    
```python
print("hello there")
```

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

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

Evaluate the expression with <span class="badge badge-small">Inline command</span>.

#### 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 <span class="badge badge-small">Inline command</span>.

The configured inline chat model uses the current file as context and writes the response directly into the document.
Configure the model in `[models]`:
    
```ini
[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. |

{ .text-center .muted }
Example

```ini
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. |

{ .text-center .muted }
Example

```ini
eol_mode                        lf
eol_symbols_visible             false
```

The EOL mode can also be changed for the current buffer from the <span class="badge badge-small">Command Palette</span>.
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. |

{ .text-center .muted }
Example
    
```ini
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. |

{ .text-center .muted }
Example

```ini
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:
    
```ini
-- 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](https://ollama.com/).

{ .text-center .muted }
Example

```ini
[models]

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

- The `code_completion` setting is used for inline code suggestions and works best with fill-in-the-middle (FIM) models.
- The `inline_chat` setting 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.

{ .text-center .muted }
Example

```ini
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:

```ini
undo                            Cmd + Z, Control + /
```

Multiple bindings are additive and can be customized independently.
Use the names <span class="badge badge-small">Comma</span>, <span class="badge badge-small">Period</span>, <span class="badge badge-small">Plus</span>, and <span class="badge badge-small">Minus</span> when binding those punctuation keys.

```ini
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 <span class="badge badge-small">Command Palette</span>.

Common navigation commands include:
    
```ini
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:
    
```ini
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:
    
```ini
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_eol` command 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:
    
```ini
select_next_match
unselect_last_match
select_matches

line_add_caret_up
line_add_caret_down

add_cursors_to_line_starts
```

{ .text-center .muted }
For example, the default bindings are
    
```ini
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:
    
```ini
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:
    
```ini
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:
    
```ini
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.

{ .text-center .muted }
Example

```ini
[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 <span class="badge badge-small">Command Palette</span>.

{ .text-center .muted }
For scripting functions and plugin development, see the [API Reference](/api-reference/index.html).

## Themes

Themes are named sections in the configuration file.

{ .text-center .muted }
Example

```ini
[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:

```ini
keyword                         #FF79C6
```

A foreground color and modifier:

```ini
keyword                         #FF79C6, bold
```

A foreground and background color:

```ini
_link                           #0081FF, #0081FF
```

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

Or a foreground, background, and modifier:

```ini
keyword                         #FF79C6, #282A36, italic
```

Supported modifiers are `bold` and `italic`.

## Example config

```ini
[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
```

{ .text-center .muted }
Most settings can be changed immediately.
Settings marked as requiring a restart take effect after the next relaunch.