koshi at a glance
koshi's vocabulary, the default keys, the shell commands, and the properties that shape how it works — including terminal images and per-client views.
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
| Term | What it means in koshi |
|---|---|
| Session | A process of its own that owns tabs. It keeps running after every terminal leaves. |
| Client | One terminal attached to a session. Several can attach at once. |
| Tab | Holds one layout of panes. Created, closed, moved, and switched. |
| Pane | One process, with its own terminal screen and scrollback. |
| Leader | The key a shortcut starts with. Ctrl by default, and configurable. |
| Profile | A saved layout of tabs, panes, commands, directories, and environment values. |
The default keys
The default leader is the Ctrl modifier run, so <leader>p is
<C-p>.
| Keys | Result |
|---|---|
| <C-p> h j k l | Open a pane left, down, up, right |
| <C-p> n | Open a pane in the configured direction |
| <C-p> x | Close the pane and its process tree |
| <C-p> ←↓↑→ | Focus a nearby pane |
| <C-s> ←↓↑→ | Move a pane border one cell |
| <C-t> n / x | Open / close a tab |
| Tab / Shift+Tab | Next / previous tab |
| Alt+f | Fullscreen the focused pane, and back |
| <C-l> | Lock input — every key goes to the program |
| <C-q> | Leave the session, which keeps running |
Rebind any of it in keybinding.kdl. See
How keys work.
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 attachedThree 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.
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.
Remote sessions are built in
koshi share grant alice # on the machine holding the sessions
koshi attach --remote work quiet-heron # from anywhere elseTLS, with the server's certificate pinned on the first connection, 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 version 1:
| File | Holds |
|---|---|
koshi.kdl | App settings |
themes/<name>.kdl | Interface colours |
keybinding.kdl | Keys and the modes they live in |
profile/<name>.kdl | A saved layout |
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 installationNothing 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 jsonSee CLI conventions.
What you get in the box
Split and stacked panes, pane gaps, fullscreen, 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.