Conventions

Every koshi subcommand works the same way from inside a session and from any other shell. What changes is how the target is chosen.

Choosing a target

• Inside koshi — an omitted target means the current session, tab, pane, or client.
• Outside koshi — give a target, unless exactly one session is running. Then koshi uses it. Zero or several running sessions fail rather than guess.

Targets are passed as --session, --tab, --pane, and --client, and take the ids that create and list commands print.

One running session plus koshi new-tab puts a tab in that session. Two running sessions plus the same command fails with several sessions are running; name one with --session <name-or-id>.

new-pane, run, and new-tab need a terminal attached to the session. A session with nothing attached refuses them with no client is attached to the session.

Names and ids

A flag written NAME_OR_ID takes either the target's generated name or its printed id:

koshi kill-session S-amber-fox
koshi kill-session session-3f2a…

koshi generates every session and tab name; no command sets one. A session name reads S-<adjective>-<noun> and a tab name T-<adjective>-<noun>, with English, Japanese, or Traditional Chinese words, such as S-amber-fox or T-しずか-りす.

A value that reads as an id is always used as an id — it never falls back to a name lookup. A name that several targets share is refused, and the error lists every matching id. --pane and --client take ids only.

What create commands print

Ids print on stdout in creation order:

koshi new-tab
[TAB ID]: tab-<uuid>
[PANE ID]: pane-<uuid>

Each line is labelled, so take the id off the end of it before reusing it:

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

Commands that create nothing print no id line.

Output format

List and inspect commands accept --format:

koshi list-panes --format table   # default, for reading
koshi list-panes --format json    # for scripts

Launching

The command map