koshi.kdl
The main koshi settings file — theme, panes, scrollback, layout, mouse, copy, terminal, logging, and self-update.
koshi.kdl holds the app settings. It sits directly in the
config directory. version is
required; everything else is optional and grouped into blocks. theme is the
one top-level setting.
A bad field is skipped at startup, keeps its default, and is logged — the rest
of the file still applies. The exception is update: a bad value there drops
the whole file for that launch. koshi config check rejects bad fields
outright.
theme
theme "midnight" loads themes/midnight.kdl. A missing, invalid, or omitted
theme — or "default" — uses the built-in colours. See
Themes.
| Key | Value | Default | Since |
|---|---|---|---|
theme | string — the themes/<name>.kdl to use, without .kdl | "default" | ≥ 0.1.0 |
pane
| Key | Value | Default | Since |
|---|---|---|---|
min-cols | integer — smallest width a pane may shrink to | 2 | ≥ 0.1.0 |
min-rows | integer — smallest height a pane may shrink to | 1 | ≥ 0.1.0 |
scrollback
| Key | Value | Default | Since |
|---|---|---|---|
max-lines | integer — lines of history kept per pane (negative means 0: no scrollback) | 10000 | ≥ 0.1.0 |
max-bytes | integer — byte ceiling on that history (negative means 0) | 33554432 (32 MiB) | ≥ 0.1.0 |
scroll-on-input | boolean — typing while scrolled up snaps the view back to the newest line | #true | ≥ 0.1.0 |
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
| Key | Value | Default | Since |
|---|---|---|---|
new-pane-direction | "left" | "right" | "up" | "down" — where a new pane opens when the command does not say | "right" | ≥ 0.1.0 |
mouse
| Key | Value | Default | Since |
|---|---|---|---|
border-resize | boolean — drag a pane border to resize it | #true | ≥ 0.1.0 |
scroll-lines | integer — lines per wheel notch | 3 | ≥ 0.1.0 |
wheel | "scroll-scrollback" | "ignore" | "scroll-scrollback" | ≥ 0.1.0 |
copy
| Key | Value | Default | Since |
|---|---|---|---|
trim-trailing-whitespace | boolean — drop trailing blanks from copied lines | #true | ≥ 0.1.0 |
terminal
| Key | Value | Default | Since |
|---|---|---|---|
term | string — the TERM value child programs see | "xterm-256color" | ≥ 0.1.0 |
colorterm | string — the COLORTERM value child programs see | "truecolor" | ≥ 0.1.0 |
default-shell | string — the shell to launch | your $SHELL (%COMSPEC% on Windows) | ≥ 0.1.0 |
logging
koshi writes logs/koshi-log-<session-id>.log below the state directory.
Disabled logging creates no file at all.
| Key | Value | Default | Since |
|---|---|---|---|
enabled | boolean — write a log file at all | #false | ≥ 0.1.0 |
level | "info" | "warning" | "error" — lowest severity written | "warning" | ≥ 0.1.0 |
format | "pretty" | "json" | "pretty" | ≥ 0.1.0 |
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.
update
A bad value in this block drops the whole koshi.kdl for that launch, not just
the field.
| Key | Value | Default | Since |
|---|---|---|---|
auto-check | boolean — check GitHub for a newer koshi at startup | #true | ≥ 0.1.0 |
check-interval-days | integer — days between checks | 14 | ≥ 0.1.0 |
allow-prerelease | boolean — offer pre-release builds too | #false | ≥ 0.1.0 |
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"
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
}