Introduction

koshi is a terminal multiplexer. It runs several shells and programs inside one terminal window and handles pane layouts, tabs, terminal emulation, scrollback, keyboard shortcuts, mouse input, process cleanup, and terminal images.

Each pane holds its own process, its own terminal screen, and its own scrollback. Tabs hold layouts of panes. A session holds tabs.

The session outlives the terminal

A session runs in its own process. Your terminal is a client attached to it. Close the terminal, lose the SSH link, or press the quit shortcut, and the session keeps running with every pane alive.

koshi                  # start a session and attach this terminal to it
koshi detach           # leave it running
koshi attach           # come back to it

Several terminals can watch one session at once, each with its own focused pane, its own tab, and its own colours. One of them can sit on another machine.

Images stay with the session

Programs in a pane can draw images with the Kitty graphics protocol, iTerm2 inline images, or Sixel. koshi keeps each image at its cell placement through scrolling, scrollback, resizing, and screen switches.

Each terminal probes its own capabilities. It uses Kitty first, then iTerm2, then Sixel. A terminal that supports none shows terminal image unavailable in the cells the image covers. Set image-support #false in koshi.kdl to keep the placeholders and send no image bytes. See Terminal images.

Your keys and your view are yours

The terminal you sit at reads your own keybinding.kdl and decides what each key means. It sends the session the action name, never the key — so your own shortcuts follow you to a session on any machine, and you never edit a keybinding file on the other one.

The focused pane, the active tab, the fullscreened pane, the scroll position, the selection, and the lock mode belong to your terminal too. Two people on one session sit in different tabs and type into different panes without moving each other's screen.

See Your keys, your view.

Reach it from another machine

koshi share grant alice                  # on the machine holding the sessions
koshi attach --remote work quiet-heron   # from anywhere else

TLS, a certificate pinned on the first connection, and an access token you grant and revoke. Nothing is reachable until you say so. See Remote sessions.

What is built in

Panes, tabs, layouts, keybindings, themes, and saved layouts ship with the program. There is no plugin to install before koshi becomes useful.

• Sessions — run in their own process, survive the terminal, and take several attached clients at once, each with its own keys and its own view.
• Panes — split left, right, up, or down; leave configurable gaps between splits; stack several in one slot; fullscreen one and restore the layout afterwards.
• Tabs — create, close, move, and switch.
• Keyboard — multi-key shortcuts, a leader you choose, on-screen hints, and conflict checks.
• Mouse — focus panes, drag borders, scroll, select text, copy through OSC 52 even over SSH.
• Terminal images — decode Kitty, iTerm2, and Sixel output and render each image in every attached terminal that can show it.
• Config — four optional KDL files for settings, colours, keys, and saved layouts, read per terminal.
• Control from a shell — open panes, move tabs, send input, and inspect a running session from outside it, on this machine or another one.
• Remote sessions — attach over TLS with a pinned certificate and an access token, and reconnect on your own when the link drops.
• Same-machine sharing — let the other users of this machine list, attach to, and kill your sessions.
• Update in place — koshi update restarts each running session into the new build, keeping its panes, their programs, and their scrollback.
• Installation check — koshi doctor rates config, shell, terminal, directories, router, and remote access.

Requirements

Next