FAQ
What koshi is, whether your work survives closing the terminal, how two people share one session, how remote attach works, and what it costs — answered in one place.
Short answers to what people ask before installing koshi. Each one links to the page that covers it in full.
What is koshi?
koshi is a terminal multiplexer written in Rust. It runs several shells and programs inside one terminal window and handles pane layouts, tabs, terminal emulation, scrollback, keyboard shortcuts, mouse input, and process cleanup. It is MIT licensed and runs on Linux, macOS, and Windows, on x86-64 and ARM64.
See Introduction.
Does my work survive closing the terminal?
Yes. A koshi session runs in its own process, so closing the terminal, losing
an SSH link, or pressing the quit shortcut leaves every pane running. Run
koshi attach to rejoin it, from the same machine or another one.
See Attach and detach.
Can two people use one koshi session at the same time?
Yes. Several terminals can attach to one session at once, and each keeps its own focused pane, active tab, fullscreened pane, scroll position, text selection, lock mode, theme, and keybindings. One person can switch to tab 2 while the other stays on tab 1, and neither moves the other's screen.
See Your keys, your view.
Do my keybindings follow me to another machine?
Yes. The terminal you sit at reads your own keybinding.kdl and decides what
each key means, then sends the session the action name —
core:new-pane-right — never the key itself. A session on another machine
works the same way, so you never edit a keybinding file on the far end.
See Your keys, your view.
Can koshi attach to a session on another machine?
Yes. koshi attach --remote <server> attaches over TLS. The first connection
pins the certificate the server presents, and a later connection presenting a
different one is refused. Access is granted with a token you scope to one
session or all of them, and revoke at any time. A dropped link dials again for
up to two minutes and restores your tabs, focus, and scroll position.
See Remote sessions and the setup walkthrough.
How is koshi configured?
koshi reads four optional KDL files: koshi.kdl for app settings,
themes/<name>.kdl for colours, keybinding.kdl for keys, and
profile/<name>.kdl for saved layouts. Each present file declares version 1.
With none present, built-in defaults apply. koshi config check validates
every file and koshi config explain <KEY> describes one setting.
See Configuration.
Can panes show terminal images?
Yes. koshi decodes Kitty graphics protocol, iTerm2 inline images, and Sixel.
Each terminal chooses the protocol it supports. Images keep their placement
through scrolling, scrollback, resizing, and screen switches. A terminal with
no supported protocol shows terminal image unavailable in the covered cells.
Set image-support #false to disable native image output for that terminal.
See Terminal images.
Does koshi run on Windows?
Yes. koshi ships prebuilt binaries for Linux, macOS, and Windows on x86-64 and ARM64, and CI tests all three. Install on Windows with Scoop or the PowerShell release script.
See Installation.
Can I control koshi from a shell script?
Yes. Every pane, tab, input, focus, lock, and session operation has a shell
command that works from inside a pane or any other shell, and every list and
inspect command takes --format json.
See CLI conventions.
How do I update koshi without losing my panes?
Run koshi update. Since 0.3.0 it installs the new release and then restarts
each running session into it, keeping the panes, the programs running in them,
and their scrollback; an attached terminal rejoins on its own.
koshi server-version shows which sessions moved.
See Update and versions.
Can other users of my machine reach my sessions?
Only if you turn it on. allow-other-users #true in your koshi.kdl lets the
other users logged in to the same machine list, attach to, and kill your
sessions, and their own koshi.kdl has to say so too. It is off by default.
Something was refused. What went wrong?
Run koshi doctor first — it rates config, shell, terminal, directories,
router, session directory, and remote access, one row each. For a refused
remote connection, every refusal and its fix is listed on one page.
See Doctor and Remote troubleshooting.
How much does koshi cost?
Nothing. koshi is free and open source under the MIT licence.