koshi at a glance

Everything koshi is, on one page: the words it uses, the keys it ships with, the commands you will type, and the three properties that shape how it works.

Read it start to finish in a few minutes, or jump to the part you need.

koshi's vocabulary

The default keys

The default leader is the Ctrl modifier run, so <leader>p is <C-p>.

Rebind any of it in keybinding.kdl. See How keys work.

In move mode, arrows choose a pane to swap with and Shift+Arrow chooses where to insert beside a pane or stack. Enter accepts the preview; Escape cancels it. Only the client making the move sees the preview. See Panes.

Detach and attach

koshi                        # start a session, attach this terminal
koshi detach                 # leave it running
koshi list-sessions          # what is still running
koshi attach                 # pick one and rejoin
koshi kill-session <NAME>    # end it for good
koshi --headless             # start one with nothing attached

Properties to know

These properties shape almost everything else in the documentation.

Your keybindings are resolved on your machine

The terminal you sit at reads your own keybinding.kdl and decides what each key means. It sends the session the action name — core:new-pane-right — never the key. A session on another machine works the same way, so your shortcuts follow you there and you never edit a keybinding file on the far end.

See Your keys, your view.

Every attached terminal keeps its own view

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

Floating panes belong to the session, their place to you

A floating pane sits above the tiled panes of every tab. Its program and scrollback belong to the session; where it sits, whether it is pinned, and whether it is minimized belong to each terminal. The tray (<C-p> w) lists them. See Floating panes.

koshi's messages go to the notification center

A pane killed by a signal, a config warning, or a refused key shows as a short toast and stays in the notification center (Alt+n). See Notifications.

Terminal images use each terminal's protocol

A pane can draw Kitty, iTerm2, or Sixel images. Each attached terminal probes its own capabilities and chooses the protocol it supports. Images keep their cell placement through scrolling, resizing, and screen switches. A terminal without image support shows terminal image unavailable in the covered cells.

See Terminal images.

Terminal input keeps key details

Koshi forwards key presses, repeats, releases, text, and modifiers to pane programs with the Kitty keyboard protocol. Terminal programs can also set horizontal margins and origin mode. See Keyboard input.

Remote sessions are built in

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

TLS 1.3, a certificate fingerprint checked before the secret is sent, and an access 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.

Configuration is KDL

Four optional files, each declaring a schema version. Version 2 is current; version 1 files migrate automatically before a session server or router reads them:

koshi config check                 # validate every file
koshi config explain <KEY>         # what one setting does
koshi keys conflicts               # clashes and unreachable shortcuts
koshi doctor                       # rate the whole installation

Nothing is required — with no files present, built-in defaults apply. See Configuration.

Scripting it

Every pane, tab, input, focus, lock, and session operation has a shell command, and every list and inspect command takes --format json:

pane=$(koshi new-pane --direction right | awk '{print $NF}')
koshi input --pane "$pane" "cargo watch -x test"
koshi list-panes --format json

See CLI conventions.

What you get in the box

Split and stacked panes, pane gaps, fullscreen, moving existing panes, keyboard and mouse resize, tabs, per-pane scrollback, true colour, CJK and emoji, terminal images through Kitty, iTerm2, and Sixel, OSC 52 clipboard copy over SSH, 25 themes, saved profiles, per-session logging, remote sessions, same-machine sharing, in-place updates, and koshi doctor. Linux, macOS, and Windows, on x86-64 and ARM64. MIT licensed.

Next