koshi.kdl

koshi.kdl holds the app settings. It sits directly in the config directory. version is required; everything else is optional. theme, image-support, allow-beta-features, allow-other-users, remote-listen, remote-reconnect, shared-sessions-dir, 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-<uuid>.log below the state directory, named by the session's bare UUID. 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.

image-support

Read by your terminal. Each terminal probes its own capabilities and chooses Kitty, iTerm2, or Sixel output when the setting is on. A terminal with none of those protocols keeps the text and the terminal image unavailable placeholder.

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.

remote-listen

Read by every koshi process on the machine holding the sessions.

remote-listen "0.0.0.0:7654" names the address the remote listener binds, and does nothing else.

allow-other-users is a separate switch, about other users logged in to this same machine. Neither key turns the other on.

See Remote sessions.

remote-reconnect

Read by your terminal. It applies only to a terminal viewing a session on another machine, reached with koshi attach --remote.

On, a link that drops dials that machine again — after 1 second, then 2, 4, 8, and 8 before every dial after that — for up to 120 seconds. While it waits, the tab strip reads a tag shaped like RECONNECTING (attempt 4, retry in 8s). Joining again puts back the tab you were on, the focused pane of each tab, the fullscreened pane of each tab, and the scroll offset of each pane. Keys typed while the link is down are dropped; a resize is kept.

A refusal no dial can change stops the dialing at once. Off, a dropped link ends the terminal, printing how to attach again by hand. A link to a session on this machine ends the terminal either way.

See Reconnecting.

allow-other-users

Read by the session for every connection and every request, and by every koshi command as it runs — so turning it off shuts those users out without a restart.

Your sessions are yours alone unless you say otherwise. Turning this on lets every other user logged in to the same machine list your sessions, attach to them, and kill them.

Both files have to say so. Your koshi.kdl opens your sessions to other users; their own koshi.kdl makes their koshi look for sessions that are not theirs.

Turning it on reaches the sessions you start after the change. A running session keeps the socket it already has until it restarts, and koshi update restarts every session it finds. A session started with koshi --headless --allow-other-users keeps other users for its whole life and never reads this key.

See Sharing with other users.

shared-sessions-dir

Read by every koshi process for itself.

Where the session sockets other users reach are kept. Set it to a directory every user who shares the machine can enter, such as /var/run/koshi. Leave it out and koshi uses the machine-wide directory for the platform: /tmp/koshi on Linux and macOS, %ProgramData%\koshi on Windows.

Every user who shares the machine has to name the same directory. A user whose file names a different one looks in that one and finds nobody.

This only says where the sockets go. Nobody else reaches them until allow-other-users is on.

Every setting at its default

default-shell, remote-listen, and shared-sessions-dir are commented out — they have no fixed default. default-shell comes from $SHELL or %COMSPEC%, remote-listen is unset, and the shared sessions directory is /tmp/koshi on Linux and macOS, %ProgramData%\koshi on Windows.

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

theme "default"
image-support #true
allow-beta-features #false
allow-other-users #false
// remote-listen "0.0.0.0:7654"  // sets the address; opens no port on its own
// shared-sessions-dir "/var/run/koshi"  // optional override
auto-close-session #false
remote-reconnect #true

pane {
    min-cols 2
    min-rows 1
    gap 0
}

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
}