Overview

koshi reads four optional KDL file types. With none present, built-in defaults apply. Every file that does exist must declare a supported version.

Where the files go

The two top-level files sit in the config directory. Themes and profiles use their own subdirectories.

<config dir>/
    koshi.kdl
    keybinding.kdl
    themes/
        midnight.kdl
        solarized.kdl
    profile/
        dev.kdl
        writing.kdl

koshi has no config-path override. Linux still follows XDG_CONFIG_HOME.

koshi config path

Whose setting is it

A session runs in its own process, and your terminal is a client attached to it. Each side reads the config files it needs.

allow-other-users is the exception to "once, at startup": the session reads it again for every connection and every request another user makes, so turning it off shuts those users out without a restart.

Two terminals watching one session can therefore wear different colours and use different keys, but never disagree about pane sizes or scrollback.

Versions and migration

Every file declares one top-level version with one integer argument, starting at 1, and no child block. The current schema is version 2:

version 2

koshi config check     # validate every present file, change nothing
koshi config migrate   # validate, then apply registered schema steps

check fails on missing versions, bad KDL, bad values, unknown keys, and unsupported versions, and reports errors from all files together.

migrate validates every file before writing, applies each version step in order, and validates after each step. Version 1 files migrate to version 2. An unreadable file, malformed KDL, unsupported version, or missing step stops this command before any file is written. Unknown keys and bad values are kept by the migration, though koshi config check still reports them. Changed files are replaced atomically, one at a time; symlinks stay and their targets change. A write error lists the files already completed and marks the failed one as possibly changed.

Session servers and the router also migrate config before reading it at startup. If that migration fails, they report the error and continue with the files as they are. Startup migration does not repair bad fields: unknown keys and bad values remain in the migrated file and koshi config check still rejects them.

When a file has a mistake

• koshi.kdl and themes are field-partial. A bad field keeps its default and the other valid fields still apply. koshi logs each skipped field.
• Keybindings and profiles are all-or-nothing. Any error drops the whole file.
• Every problem names its line and column, such as line 3, column 5: ignored `pane.gap`: expected an integer. Problems come in file order.
• Unknown keys name the nearest valid key. min-col 2 inside pane produces unknown key `pane.min-col`; did you mean `pane.min-cols`?. koshi config check treats that typo as an error even though startup would keep the other fields.
• A missing or invalid theme falls back to the built-in default colours and logs why.

Explain one setting

koshi config explain koshi.scrollback.max-lines

Keys are file-qualified: koshi.pane.min-cols, keybinding.chord-timeout-ms, theme.colors.accent, profile.version. The command prints which file the setting belongs to, its default, and what it does.