Koshi FAQ

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 gives the fingerprint of the server's certificate, which koshi share grant prints on the server, and a connection to a server presenting a different certificate 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.

Can I move an existing pane?

Yes. Press <C-p> m to preview a swap or an insertion beside another pane, including in another visible tab. Enter accepts the move and Escape cancels it. koshi move-pane swaps with a visible neighbor immediately; koshi place-pane moves an existing pane into another tab's tiled layout.

See Panes.

Does koshi have floating panes?

Yes. <C-p> f opens a floating pane above the tiled layout, and <C-p> u floats the focused pane or docks it back. Each attached terminal moves, pins, minimizes, and restores floating panes on its own screen, and the tray (<C-p> w) lists them all.

See Floating panes.

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 a schema version; version 2 is current, and version 1 files migrate automatically when a session server or router starts. With no files 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. 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, on Linux or macOS. 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, and has no effect on Windows.

See Sharing with other users.

Something was refused. What went wrong?

Run koshi doctor first — it rates config, shell, terminal, directories, log files, 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.