Your keys, your view
Each terminal attached to a koshi session resolves its own keybindings and owns its own focus, tab, zoom, scroll, and selection — so two people share one session without moving each other's screen.
A koshi session is shared. What you see of it is not.
Two terminals can attach to one session at the same time. They share the panes, the processes, and the scrollback. They share nothing else.
Your keybindings stay on your machine
The terminal you sit at reads your own keybinding.kdl and decides what each
key means. It then sends the action name to the session, never the key.
you press <C-p> l
your terminal resolves it against your keybinding.kdl
the session gets core:new-pane-rightThe session never sees <C-p> l. A key your keymap does not bind is the only
thing that travels as a key, and it travels as input for the pane you are
typing into.
This holds for a session on another machine too, so your own shortcuts follow you there. You never edit a keybinding file on the other machine.
The same is true of your theme. Two terminals showing one session can wear different colours and use different keys, and neither notices the other's.
Each 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 to the session.
Two people attach to one session. One switches to tab 2; the other stays on tab 1. Each types into the pane they focused. Neither moves the other's screen.
| Your terminal owns | The session owns |
|---|---|
| Which tab it is looking at | Tabs, panes, and their processes |
| Which pane is focused | Scrollback and its size limits |
| Which pane is fullscreened | TERM, COLORTERM, and the default shell |
| Its scroll position in each pane | auto-close-session |
| Its text selection | |
| Its theme and its keybindings | |
| Its image protocol and native image output setting | |
| Its lock mode and mouse-selection mode |
What is still shared
Pane sizes. A tab solves against the smallest terminal viewing it on each
axis, minus the top tab bar row and the bottom hint row. Two clients on one tab,
one 80x24 and one 120x40, both get viewport 80x22.
Pane content. Nobody sees a different screen for the same pane. A client that misses an event resyncs from the session instead of drawing a stale view.
Because a pane is painted to every client viewing its tab, anything printed in
a pane is read by everyone attached — which is why the
koshi share verbs refuse to run inside a pane
while someone is attached from another machine.
Where each setting is read
| Read by | Settings | When |
|---|---|---|
| The session | pane, scrollback, terminal, auto-close-session | Once, when the session starts |
| Your terminal | theme, themes/<name>.kdl, keybinding.kdl, mouse, copy, layout.new-pane-direction, image-support, remote-reconnect | Every time it attaches |
| Every process | logging, update, allow-beta-features, shared-sessions-dir, remote-listen | For itself |
| The session, again and again | allow-other-users | Every connection and every request another user makes |
A terminal that attaches later cannot change a session-owned setting from its
own file. allow-other-users is the exception: the session re-reads it for
every connection and every request, so turning it off shuts other users out
without a restart. See
Whose setting is it.
Pane input is scoped to what you can see
koshi input reaches only panes visible to the client that issued it, and a
new pane inherits the working directory of the terminal that asked for it. A
command with no target uses the current session, tab, pane, or client of the
pane you ran it in.
See who is attached
koshi list-clients
koshi inspect client <CLIENT_ID>
koshi debug dump-layout # per-client focus and rectangleskoshi debug dump-layout is where the split shows plainly: one client tiled
and one with a pane fullscreen give that tab two sets of rectangles, from one
split tree.