koshi.kdl

koshi.kdl holds the app settings. It sits directly in the config directory. version is required; everything else is optional. theme, allow-beta-features, and auto-close-session are top-level; the rest are grouped into blocks.

Each section says who reads it: the session, which took its copy when it started, or your terminal, which reads its own file every time it attaches. See Whose setting is it.

theme

Read by your terminal. Two terminals showing one session can wear different colours.

theme "midnight" loads themes/midnight.kdl. A missing, invalid, or omitted theme — or "default" — uses the built-in colours. See Themes.

pane

Read by the session. Panes are the session's, so every terminal sees the same sizes.

scrollback

Read by the session, including scroll-on-input, so every attached terminal gets the same answer.

scroll-on-input #false keeps the view parked while the input still goes through. Only the primary screen follows; the alternate screen is left to the full-screen program on it.

layout

Read by your terminal. Two terminals viewing one session can differ.

The new-pane-<side> keybindings and an explicit --direction name their own side and ignore this.

mouse

Read by your terminal — the mouse is its own.

copy

Read by your terminal — the copy is made where the selection was dragged.

terminal

Read by the session — it starts the programs in the panes, so it decides what they are told.

logging

Read by every koshi process for its own log file. koshi writes logs/koshi-log-<session-id>.log below the state directory. Disabled logging creates no file at all.

info includes normal lifecycle events, warning recoverable problems, and error failures that stop koshi. Each level includes the more severe ones. Logs store ids and byte counts — never typed or copied text. Crash reports are separate and always on; see Logging and crash reports.

update

Read by every installed koshi for itself.

allow-beta-features

Read by every koshi process when it starts, so the interactive session and the koshi commands you type all get the same answer.

Some features are finished code that has not been used enough to be turned on for everyone. They are off unless you say otherwise. Turning this on runs all of them; there is no per-feature switch.

A beta feature you have not turned on refuses and says so, naming itself and the line to add:

koshi: `koshi <command>` is a beta feature and did nothing; add a top-level
`allow-beta-features #true` line to koshi.kdl to run it

Nothing crashes and nothing is lost; the command exits non-zero having done nothing.

auto-close-session

Read by the session, from the koshi.kdl it saw when it started. A terminal attaching later cannot change it.

A terminal leaving a session normally leaves the session running with nothing attached, so koshi attach can rejoin it later. Turning this on ends the session once the last terminal leaves.

koshi counts the terminals after the one that left is gone. If any are still attached, the session keeps running; only an empty session ends.

Ending it asks every program in the session to stop, waits up to three seconds, then kills whatever has not exited — long enough for a shell to write its history and an editor its swap file. On Windows a program cannot be asked to stop, so everything is killed at once. koshi kill-session skips the wait.

Every way of leaving counts: the quit keybinding (<C-q> by default), koshi detach, closing the terminal, and moving the terminal to another session with koshi attach <session> from inside a pane.

Every setting at its default

default-shell is commented out because its default comes from $SHELL or %COMSPEC%.

// koshi.kdl — the complete default configuration.
version 1

theme "default"
allow-beta-features #false
auto-close-session #false

pane {
    min-cols 2
    min-rows 1
}

scrollback {
    max-lines 10000
    max-bytes 33554432       // 32 MiB
    scroll-on-input #true
}

layout {
    new-pane-direction "right"
}

mouse {
    border-resize #true
    scroll-lines 3
    wheel "scroll-scrollback"
}

copy {
    trim-trailing-whitespace #true
}

terminal {
    term "xterm-256color"
    colorterm "truecolor"
    // default-shell "/bin/zsh"  // optional override
}

logging {
    enabled #false
    level "warning"
    format "pretty"
}

update {
    auto-check #true
    check-interval-days 14
    allow-prerelease #false
}