Quick start

Open a session

koshi

That gives you one tab with one shell pane. The bar at the top lists tabs; the bar at the bottom shows key hints once a shortcut is pending.

The default leader is Ctrl. Press the leader chord, then the direction:

Keys	Result
`<C-p>` `l`	Open a pane to the right
`<C-p>` `h`	Open a pane to the left
`<C-p>` `j`	Open a pane below
`<C-p>` `k`	Open a pane above
`<C-p>` `n`	Open a pane in the configured direction

A new pane inherits the working directory of the pane you split from.

Keys	Result
`<C-p>` `←↓↑→`	Focus a nearby pane
`<C-s>` `←↓↑→`	Move the pane border one cell
`Alt+f`	Fill the tab with the focused pane, and back
`<C-p>` `x`	Close the pane and its process tree

<C-q> takes your terminal out of the session. It does not end the session — every pane keeps running.

koshi list-sessions      # what is still running
koshi attach             # pick one and rejoin it

koshi detach from inside a pane does the same as the quit shortcut. See Attach and detach.

koshi kill-session       # the only running session

Or set auto-close-session #true in koshi.kdl to end each session once its last terminal leaves.

When a program needs the keys koshi is holding, lock input with <C-l>. Every keystroke then goes straight to the program until you unlock.

koshi keys list
koshi actions list

Nothing above needs a config file. When you want to change it, start at Configuration.

koshi doctor

One row per check, each rated ok, warn, or fail. See Doctor.

On the machine holding the sessions, name a listen address in koshi.kdl and grant a token:

koshi.kdl

version 1
remote-listen "0.0.0.0:7654"

koshi share grant alice     # answer y to open the port; copy the token

From the machine you sit at:

export KOSHI_REMOTE_SECRET='<the secret the grant printed>'
koshi attach --remote laptop.local:7654 --save-as work quiet-heron

Full walkthrough: Setup.

Write a profile once and open the whole desk with one command:

koshi --profile dev