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, reduced-motion, stay-in-pane-placement-mode-after-placement, allow-beta-features, allow-other-users, remote-listen, remote-reconnect, remote-link-timeout-ms, max-frames-per-second, 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.

Dragging the corner of a tiled pane moves both borders that meet there. A floating pane takes the mouse on every cell it covers; see Floating panes.

copy

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

notifications

Read by your terminal. Sets the toast that shows each new notification for a short time. The notification center keeps every notification whatever these keys say.

A toast slides in from the side of its corner in 1 second, stays for toast-duration-ms, then slides out in 1 second. When more notifications wait, each part takes half a second. A value the key does not accept is skipped with a warning.

pane-clipboard-writes

Read by the session, when it starts and again when it restarts into a new build.

A program in a pane can copy text by writing OSC 52, such as printf '\033]52;c;aGk=\a', which copies hi, or by running a clipboard tool: pbcopy, xclip, xsel, or wl-copy. This block decides whether koshi passes those copies on to your terminal.

With allow #false, an OSC 52 copy reaches no clipboard, and a clipboard tool runs as it does outside koshi.

With allow #true:

• An OSC 52 copy goes to the terminal of every client whose focused pane wrote it, and that terminal sets its own clipboard. The copy keeps the clipboard it names (c, p, q, s, or 0 to 7). A copy longer than max-copy-bytes reaches no terminal. A request to read the clipboard gets no answer.
• On Linux and macOS, each pane started while it is on finds stand-ins for pbcopy, xclip, xsel, and wl-copy first on its PATH, one for each of those tools the session found when it started. A plain-text copy made through a stand-in goes to every client attached with koshi attach --remote whose focused pane is that pane. The real tool runs too, unless every client focusing the pane is on another machine and took the copy.

Example: printf hi | xclip -selection clipboard in a pane that only a terminal on another machine focuses puts hi on that terminal's clipboard. In a pane your terminal on the session's machine focuses, the real xclip runs.

The real tool runs alone for a read, a clear, a copy that is not plain UTF-8 text, a copy longer than max-copy-bytes, and a copy the session does not take within 5 seconds.

No stand-in sees a tool started by its full path (such as /usr/bin/xclip), through sudo, or inside a container; a tool in a folder that a shell startup file puts before the stand-ins on PATH; a tool installed after the session started; or a pane started before allow #true took effect. On macOS, a login shell such as zsh -l runs path_helper, which puts /usr/bin first, so pbcopy runs from there. The shell koshi starts in a new pane is not a login shell.

On Windows no stand-in replaces a clipboard tool; clip.exe copies on the session's machine only.

terminal

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

"on-request" sends enhanced sequences when a program asks for them. "always" also sends them for keys that share legacy bytes, even when the program did not ask. See Keyboard input.

logging

Read by every koshi process for its own log file. koshi writes, in logs/ below the state directory, one koshi-log-<uuid>.log per session, named by the session's bare UUID, and koshi-log-router.log for the router. 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. On Linux and macOS, a SIGHUP, SIGTERM, SIGINT, or SIGQUIT that koshi does not ignore is a leaving too; on Windows, Ctrl+C or Ctrl+Break.

These are not a leaving, so the session keeps running even when no terminal is left:

• a terminal on another machine whose link drops, or that is killed with kill -9;
• a restart into a new build, such as the one koshi update starts. Each attached terminal reconnects by itself, and keys typed meanwhile reach the restarted session in order.

remote-listen

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

remote-listen "0.0.0.0:7654" names the IP address and port the remote listener binds, and does nothing else. Use an IP address; hostnames are ignored with a warning.

The router reads this line when it starts. A line you add, change, or remove while the router runs applies after koshi restart-servers. Until then the router keeps the address it read. koshi share grant, koshi share open, and koshi doctor name the restart when the two differ.

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, the scroll offset of each pane, and your floating panes: which show, where each sits, which are pinned or minimized, and which one takes your keys. Keys and pastes typed while the link is down are dropped; the link that comes back reports the terminal's size then. The quit keybinding leaves at once while the link is down.

Each dial uses the saved server as koshi remote list shows it at that moment, so a koshi remote edit or koshi remote set-secret made while attached takes effect at the next dial.

A refusal no dial can change stops the dialing at once, and so does a saved server that is no longer at that address. 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.

remote-link-timeout-ms

Read by your terminal. It applies only to a terminal viewing a session on another machine.

The terminal sends a ping every third of this time, and the session answers when it has sent nothing for a third of this time. A link over which no byte arrives for this long has dropped: with remote-reconnect on the terminal dials again, otherwise it ends. The serving machine closes the connection after the same time without a byte from the terminal, and keeps the terminal's view for when it joins again. A paste keeps the link for as long as its bytes keep moving.

Example: with 30000, a laptop that loses its network shows RECONNECTING at most 30 seconds after the last byte arrived.

A value under 1000 is ignored with the warning must be at least 1000.

max-frames-per-second

Read by your terminal. The most frames a second the session sends this terminal; two terminals on one session can set different values. A screen that changes faster reaches the terminal as its newest state at each frame. The frame after your own key, paste, or mouse event goes at once.

A value outside 30 to 120 is ignored with the warning must be between 30 and 120. A change applies at the next koshi attach.

reduced-motion

Read by your terminal. When #true, these happen in one frame instead of sliding: the move preview, another client's accepted move, a pane you undock, a floating pane you minimize or restore, the notification center opening and closing, and a notification toast. A toast still stays for its full time.

stay-in-pane-placement-mode-after-placement

Read by your terminal. By default, the move mode opened with a key, such as <C-p> m, stays active after an accepted move so you can move another pane. Set this to #false to return to the prior input mode after each accepted move. A cancelled or rejected move does not change the mode. The setting also covers floating pane move mode (MOVE FLOAT).

A drag started on a pane's grab handle outside the move mode ends with its drop either way.

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.

This works on Linux and macOS only. On Windows koshi reads the key without an error and does nothing with it.

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 /tmp/koshi. On Windows koshi reads the key without an error and does nothing with it.

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.

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

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
remote-link-timeout-ms 30000
max-frames-per-second 60
reduced-motion #false
stay-in-pane-placement-mode-after-placement #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
}

notifications {
    toast #true
    toast-position "top-right"
    toast-duration-ms 3000
}

pane-clipboard-writes {
    allow #false
    max-copy-bytes 8388608   // 8 MiB
}

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

logging {
    enabled #false
    level "warning"
    format "pretty"
    max-log-file-size-in-mb 4
}

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