Skip to content
newdeePublic

About

Pane as an actor | Persistent terminal panes, each with its own inbox: a terminal multiplexer.

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

keepane

CI Release

中文说明 · Feature tour → · FAQ · Principles

A terminal workspace for AI agents.

keepane is a terminal multiplexer built as a workspace for AI agents and the people who run them. It gives them three things:

  • Workspace: persistent panes and sessions. Programs keep running after the terminal closes, and the layout comes back after a reboot.
  • Communication: every pane has an inbox. Panes, scripts and agents pass tasks to each other, on one computer or across two you have paired.
  • Observability: what each agent is doing and has done: its state, model, cost and context, and a trace of each step.

keepane manages the workspace and how work moves through it. It does not decide how an agent thinks or works, so it fits any vendor, model or agent harness. The usual tmux keys, commands and config file keep working.

A tour in five parts. Panes named lead, build and agent, each with its work mode and inbox on its border: a message sent to build runs there as a command, one sent to the agent waits in its inbox. A small MCP client makes a pane named tests and sends it a command. The dashboard shows every pane, a pane's events and the agent's inbox. Its chat page shows a real channel where UnifyTerm's agent and keepane's worked out a bug; the person names one with @ and says something. keepane web prints a QR code; on a phone the list shows every pane, a command typed there runs in build on the computer, and the group chat shows the same channel.

  • After you detach, the programs in the panes keep running. After a reboot, keepane resume brings the layout back; a pane closed by mistake comes back with C-b u within 10 seconds.
  • Name a pane and you can send it messages. A message goes into the inbox first and is delivered when the pane is ready: a shell runs it when it is back at its prompt, other programs read it themselves.
  • Every message carries an envelope of a fixed format, with the sender, the recipient and the task. The event log keeps 30 days; C-b v shows the panes, messages and tasks.
  • People, scripts and AI agents use the same messages; an agent can also work through the built-in MCP server, and keepane setup hooks up Claude Code, Codex, Gemini CLI, Cursor CLI, opencode or pi so that it is handed its next message when a turn ends.
  • Two computers on one network or on Tailscale pair once, the way ssh-copy-id works, and from then on panes on one send messages and commands to panes on the other (keepane link). Each machine shares the sessions, windows or panes it chooses, or gives all of itself.
  • On your phone, over Wi-Fi or Tailscale, keepane web shows every window and pane, whether each is busy or free and what waits in its inbox; what you type there runs on the computer.
  • tmux's C-b prefix, splits, copy mode, command line, config syntax (keepane import-config brings a .tmux.conf over), format strings, hooks and plugins are there.

It runs on Windows (ConPTY), with PowerShell, WSL and cmd in the panes, and on Linux and macOS, with bash and zsh.

Send work between panes

Every pane has an inbox and can be given a name. Messages queue up and are delivered according to the receiving pane's work mode.

A command sent to the pane named builder runs there with its envelope as a comment; trace-message shows it done with its output; the dashboard shows the panes, an agent's inbox and the tasks in panels, puts a message first and shows its record laid out beside the list

keepane rename-pane -t %3 builder          # -t %builder finds it from now on
keepane set-work-mode -t %builder shell    # it runs what it gets, at its prompt (from outside keepane; inside, a pane sets its own)
keepane send-message -t %builder -w 30 "cargo test"
#12 delivered to $1:@2.%3 (shell)
keepane trace-message 12 -w 600            # waits until it is done: output, success

A target can be %7 (a pane id), %builder (a name), or $1:@2.%7 (session, window and pane; whoami shows it). A full address also pins where the pane is: if the pane has been moved to another window, the delivery fails.

A pane handles messages according to its work mode:

Mode Ready when Delivery
normal (default) never on its own read with read-message; the window's flags show @
shell keepane's prompt hook sees the shell back at its prompt typed in and run
ai the agent's end-of-turn hook runs pane-ready, or its transcript says the turn is over (Claude Code, Codex, pi) typed in as a prompt, then Enter on its own

The status line shows the current pane's mode (ai and shell marked out, normal dim), and C-b q writes each pane's name and mode under its number. A status-right of your own shows it with #{pane_work_mode}.

After someone types into a pane, keepane treats it as taken until the next ready signal, so a message never lands in the middle of what is being typed. If someone presses keys while a command keepane delivered is running, the prompt that ends that command does not trigger a new message either; what a user types ahead during a command of their own is beyond keepane's reach.

What a pane is up to shows in a word (#{pane_state}, on the dashboard and the phone): idle (free for its next message), busy (its program at work), typing (keys went in with no Enter: someone is at its line, and messages wait), no-agent (an ai pane back at its shell's prompt: its agent has exited), unknown (a shell pane whose prompt hook was never heard, such as cmd's), exited; a normal pane is neither free nor busy (-). #{pane_idle} is 1 for idle.

In ai mode, if the agent has exited and a shell prompt shows again, nothing is delivered. A message is delivered the way the recipient's mode was when it was sent: text sent to an agent is never run as a shell command, even if the mode changes in between.

Every message carries a header of fixed fields, with its source and route:

[keepane id=12 task=12 from=$1:@1.%3 name=lead mode=ai to=$1:@2.%7 via=shell hop=0]

Each field is name=value, separated by spaces; no value holds a space, so a program reads it back by splitting. set -g message-envelope json writes the same fields as one line of JSON instead ({"keepane":1,"id":12,…}), as before 0.17, also in front of a shell's command; the event log always keeps the JSON.

Delivered to a shell, a short header (the id and the sender: its name, else its pane, else user) goes before the command in a form that runs nothing and stays in the history: a comment in PowerShell (<# keepane #12 from %lead #> cargo test), the argument of : in bash and zsh (: 'keepane #12 from %lead'; cargo test), of true in fish; trace-message 12 shows the rest. Several lines are joined into one command that runs them together, with one result (in bash and zsh, the last line's). Delivered to an agent, it is the header, the text and the end line [keepane end=12], pasted in; its Enter comes on its own once the paste has settled (300 ms on at the soonest, after 150 ms with nothing printed, 2 s at the latest), since an agent's input box can drop an Enter that comes on the heels of a paste (Codex does). If nothing at all is printed in answer within 2.5 s, Enter goes once more; if still nothing, show-messages says so. Someone typing in the meantime has the Enter left to them. task ties together the order, the work and the replies; hop counts how many times a message was passed on, and past message-hop-limit (8 by default) it is refused, so agents cannot answer each other in a loop.

The fields a sender chooses are given by name: --to (the pane; -t for short), --re 12 (it answers message 12, and goes to 12's sender unless --to says otherwise; -r answers the message the pane is working on) and --task 12 (it carries task 12 on). The rest is keepane's to fill in: who sent it (from, name, mode), its number, its hop and via. A sender cannot set them, so a header can be trusted and the hop limit holds:

keepane send-message --to %builder "cargo test"
keepane send-message --re 12 "the tests pass"          # to whoever sent #12
keepane send-message --to %lead --task 12 "one more thing"

Run inside a pane, set-work-mode changes only that pane; run from a terminal outside keepane, a key or the C-b : prompt, it can change any pane. So a program in a pane cannot switch another pane into shell mode, which runs its messages by itself. Renaming, managing inboxes and closing panes are not limited by this; a close can be undone with C-b u within 10 seconds. The rule is there to cut down on mistakes, not to isolate processes of the same user from each other.

Group chat

A message goes to one pane. When several agents work on one thing, a channel lets them talk in one place: each joins under a handle and a role, says what it has to say, and reads what the others said when it wants to.

The dashboard's chat page: the channel unifyterm-keepane on the left with its two members online; on the right each one's lines in a bubble of its own colour, the person's on the right

The same channel on a phone: the latest lines in coloured bubbles, and beside it @ typed in the box, the two members to name listed above it

A real channel: while this release was built, the agents of UnifyTerm and keepane worked out there how to make UnifyTerm's commands work in keepane panes, and the person asked them along the way.

keepane chat new review --topic "the 0.73 release" --tag release --tag ci
keepane chat join review --as lead --role planner   # in the lead's pane
keepane chat say review "@tester run the regression, please"
keepane chat say review --file build.log "@tester the log of the failed run"   # the file goes with it
keepane chat read review --wait 60                  # waits for something new
keepane chat who review                             # who, and from where
keepane chat list --tag ci

A file sent with --file (as many as 10, each at most chat-file-max-size, 25M by default) is copied into the channel's folder (chat dir review prints it): the line names it with its size, and a read and the message to one named say where the copy is, so an agent can open it. The board shows it in the bubble; on the web page, tap it to save it. It goes with its day's lines (chat-days). Files go to this machine's channels only, for now; a member on another machine is told which machine keeps them, not a path.

chat say review --re 42 "on it" replies to line 42 (as chat read numbers it) in its thread: who said it, and who started the thread, are told with the line quoted, and chat read review --thread 42 reads the thread whole. A reply to a reply goes in the thread's first line's, so a thread is one line and its replies. The board and the web page quote the line above a reply; on the web page, Reply under a line answers it.

A channel has an id that never changes (a UUID; chat list shows its last 8 characters, and any 8 or more of its last ones name it), a name, a topic (what it is about) and tags (to find it by). Who and where a member is (machine, session:window.pane, pane id and name, agent, model) is stamped by keepane, on the member and on every line it says: a pane joins and speaks as itself only, and the handle and role are all it chooses. You, outside every pane (the dashboard, a terminal of your own, C-b :), speak as you@<machine> without joining.

What is said stays in the channel: nobody's inbox gets it, so five agents in a channel do not each read every line. A member named with @handle is also told at once, through its inbox, with the channel and who said it, and under it what was said before since it last read (the last 20 lines; they count as read); the hop limit counts these as for any message. A member that joined with --hear all is told of every line instead, a few at a time: lines that come within 2 seconds go in one message, once nothing of the channel waits in its inbox. A pane in shell mode is never told (a message runs there as a command): the speaker is told so. A member says at most 20 lines a minute. A member naming you (@you) reaches you as an agent that is done does: a desktop notification (its button goes to that member's pane) and the done-webhook.

A member stays a member when its pane closes or the server restarts: offline (said in the channel), named but not told, until a pane of the name its pane had comes back (a resumed session brings the names back) or a pane joins with its handle; it then reads on from where it was. A member that leaves (chat leave CHAN in its pane), or that you take out (chat leave CHAN HANDLE outside every pane), is kept, marked left: not counted, not told when named, not made online again by a pane of its name; a pane joining again (with that handle, or with none from the same pane) brings it back. One offline or left longer than chat-days goes by itself. chat who says who is online, offline or left.

Channels are kept in chat\<socket>\ beside the event log, one file a day each (chat-days, 30 by default), and come back after a restart with what was said, how far you read and their members. The same commands are MCP tools (chat_list, chat_new, chat_join, chat_say, chat_read, chat_who). The dashboard's page 2 shows them. Only from outside every pane, chat delete moves a channel to chat\deleted\. The design: docs/design/chat.md.

A channel is one machine's, and panes of a paired machine (keepane link, below) join it there. From such a pane, name the channel with the machine in front:

keepane chat list DFINE                      # the channels you may look at there
keepane chat join DFINE/#review --as blog    # host:port works as well as the name
keepane chat say DFINE/#review "the post is up"
keepane chat read DFINE/#review

Its server asks that machine over link. A machine given --full may look at and join any channel; another, only those shared with it (keepane link share <host:port> #review; link unshare takes it back). The pane is stamped as its own machine stamps it, with the machine added; named with @, it is told in its inbox there; it shows online while its machine says, every 30 seconds, that the pane is still there. The person at that machine reads and says things as you@thatmachine, without joining; renaming or retagging a channel is its own machine's. The dashboard's page 2 lists the channels of every paired machine you may look at under this machine's, each with its machine's name after it.

The dashboard

C-b v (a popup) or keepane dashboard (any terminal) lays everything out in panels, lazygit style. On the left: [1] every pane, grouped by session (and first by machine while sessions of another machine are here: each machine's name and address over its sessions), with its work mode, whether it is free, its inbox, how long it has been quiet and its program (or its agent's cost and context, the total in the title), under named columns, each colour saying one thing (free green, busy yellow, messages waiting blue, a context red as it fills); in a narrow window the least needed columns give way first; [2] the chosen pane's inbox; [3] the tasks. On the right, [4] the chosen pane: its address, directory, pid, how long it has run, what it says it is doing, and then its screen live (with its colours), its scrollback, its events, its agent's trace (below), its directory in git (the Git tab: the branch and its upstream, what is changed, the latest commits and branches; in a directory outside a repository, its files two levels down), or the message or task under the cursor: moving onto one in [2] or [3] shows it at once, laid out (its stage on its colour, who sent it to whom, when each step came, then its text and what it printed; a task, its messages joined down the left). Tab, 0 1 2 3 4 and h/l move between panels, j/k within one, g/G (or Home/End) to its first or last row (the top or bottom on the right), [/] change what the right side shows; the mouse clicks and scrolls; ? lists every key. From 150 columns wide, a column on the far left holds [0] the chosen pane's directory over how the machine is doing, every second: CPU (a bar, its last 24 seconds, each core), memory, swap, disk and network a second, temperature, power, battery and processes, as far as the system says them. In [0], j/k move, h goes up a directory and l into one, as in mini.files; what is under the cursor shows on the right (a directory's entries, a file's text with its line numbers, the first 256 KiB of it; a binary file only by its size; where UnifyTerm's ut is on this machine, a picture (PNG, JPEG, GIF, WebP, BMP) as ut view draws it, in coloured half blocks, and markdown styled as ut md shows it), and l on a file scrolls it; . shows hidden entries and - goes back to the pane's directory, which [0] follows when another pane is chosen or this one changes directory. Each entry is marked by its kind with an emoji: 📁 a folder (📂 the one whose entries are on the right), 🐍 Python, 🦀 Rust, 📄 a file of no known kind, and so is each entry of the Git tab's tree (📂 a folder whose entries are listed under it); set -g dashboard-icons nerd draws a Nerd Font's icons instead, for a terminal drawn in one. Narrower, 0 puts [0] in place of the left column while it is focused. (Up to 0.60 the right side was [0]; it is [4] now.)

It also acts. On a pane: s sends it a message, r renames it, m changes its work mode, R marks it ready (unsticks it), o goes there (and closes the popup), x closes it. In the inbox: d deletes a queued message (u brings it back), K/J move it, t puts it first, Enter moves into it to scroll. Closing a pane, deleting a message and switching a pane to shell (where what it gets is run) ask first. L lists the paired machines on the bottom line, each with what it has here (has full, has 2 shared, has nothing): j/k pick one, then c connects it, x disconnects it, R takes back what it has here and D forgets its pairing (keepane link, below; R and D ask first).

> turns to the next page, < the one before (the bottom line says page 2/3, and keeps it when too narrow for every key). On page 3, [0] and the machine stay, [1] lists what this machine shares (keepane share, below), each active, missing (its file gone for now), stopped, expired or used (for once, and it went), with its time left and how often it went; [2] what happened to them, the latest first; [4] the one picked: its link, who opened it, its story and the code to scan. S in [0] shares what is under the cursor (for how long, once or not, asked); on [1], x stops one (X every one), e extends it on the same link, r shares it again on a new link, y copies its link, a hides or shows the ended ones. Sharing, stopping and sharing again ask first.

Page 2 is the group chat (above): [1] the channels, with how many are in each, how many lines you have not read, the tags and how long ago the last line was, and under each that line (/ filters them by a name or a tag); [2] the picked one's members, each in its colour, with its role, where it is and whether its pane is busy; [4] what was said there, the latest at the bottom: each one's lines in a bubble in its colour (the first six to join a channel never share one; one member's lines within 5 minutes share a bubble; yours against the right edge; a heavy left side when it names @you), each @name in that one's colour, a rule at each new day and where what you had not read begins. An offline member is a faint ○ in [2], with where it was last. At the bottom of [4] is a line to type in: s on [1], [2] or [4] (or i on [4]) starts it; a @ lists the members it may name (online first) over it, ↑/↓ pick, Tab or Enter puts one in, and Enter sends once no list is open. On [1], s says something as you, n makes a channel (its name, then its topic), t changes its topic, # its tags (+a -b); on [2], o goes to the member's pane and s says something to it. What you had not read of the channel shown counts as read. The design: docs/design/dashboard.md.

What the agents use and cost

Three agents at work in three panes, each border showing its model, cost so far and how full its context is; the dashboard listing them with cost and context and the total in its title; keepane list-agents printing the same for a script

(The agents in the recording are stand-ins that write Claude Code's and Codex's transcripts; keepane reads the real ones the same way.)

keepane knows the agents its panes run: Claude Code, Codex, pi and Cursor CLI (by the program's name, or by what node runs; Cursor's agent only from Cursor's own folder). keepane does not read Cursor's chats: for it, the CPU and memory, and the model its hook names. For each of the others, it reads the transcript the agent writes for its directory (~/.claude/projects, ~/.codex/sessions, ~/.pi/agent/sessions; CLAUDE_CONFIG_DIR and CODEX_HOME, as the server was started with, are followed), only the part written since the last read, every two seconds. From it come the model, the tokens used, the tools called, the replies made and how full the context is; from the process table, the CPU and memory of the agent and everything under it. Claude Code's subagents count toward its pane. Codex's figures are taken as Codex has them: how full the context is past the 12,000 tokens any session starts with (the share its own status line shows), and its plan's limits (rate_limits: the five-hour and the weekly window, the share used and when each starts again) when its provider says them.

The cost: pi says its own. For the others, keepane prices each model's tokens (fresh, cached, written to the cache, received; what each of Codex's running totals adds goes to the model of that moment, so a model switched mid-session is priced part by part) by LiteLLM's public price list, fetched with curl once a day (an hour later after a failed try), only while a pane runs an agent, and kept in the data directory. The list is the providers' list prices: a subscription (Claude Max, ChatGPT Pro) is billed otherwise, so read it as what the work would cost through the API. A model the list does not have is left out, and the cost then says so with a + ($2.10+: at least that). set -g agent-cost off stops the fetch and leaves cost out; KEEPANE_PRICE_LIST names a list of your own (LiteLLM's form) instead.

Where it shows: the dashboard's pane list (claude $2.10 34%: cost, context) and a line over the chosen pane with everything; a line on each agent's card on the phone page; keepane list-agents (-J for JSON, every figure a number, null when not known); and the format variables agent agent_model agent_cost agent_tokens agent_context agent_cpu agent_mem agent_tools agent_turns agent_limit (Codex's limits used, 34%/12%), for a border or the status line:

set -g pane-border-status top
set -g pane-border-format " #{pane_index} #{?agent,#{agent_model} #{agent_cost} ctx #{agent_context},#{pane_current_command}} "

What an agent is doing, step by step

The dashboard's Trace tab: an agent's turn as a waterfall, each model call and tool a bar where it ran, coloured by kind, the failed test run red

The same transcripts say what the agent did and when: each turn (your prompt to its last reply), and in it each call of the model and each tool it ran, from when to when, and whether it failed. The dashboard's Trace tab (T, or ] to it on the right) draws the chosen pane's agent as a waterfall, live (read every two seconds):

claude  claude-opus-5-5  $2.50  41k tokens  model calls 3  tools 4  ✗ 1 failed
▸ add the share command                                            5.0s
▾ fix the test running  read 2 · run 1 · agent 1                  1m40s
                                         0              50s          1m40s
  opus-5-5 1.2k tokens             10s  █████
  Read …\src\share.rs              10s       █████
  $ ✗ cargo test                   30s            ███████████████
  Task find it                     10s                           █████
    Glob **/*.rs                   1.0s                           █
  opus-5-5 thinking                40s                                ████▶

Each kind has its colour: the model magenta, reading and searching cyan, changing files yellow, running a command blue, another agent green, the web and a browser bright cyan and blue, a skill and a memory bright magenta and yellow, a hook faint, any other tool plain, a step that failed red with ✗ and why when the transcript says (denied: you said no; hook: …: a hook stopped it); a step still running is bold and ends in ▶. The key names the model and the kinds there are. A model call shows its model (◆ opus-5-5 → fable-5-2 on a switch), a command follows a $ as typed, a file its end. Three or more finished steps of a kind in a row (not the model's, an agent's, a failed or a background one) are one row: the last, with +N (one after another) or ×N (all at once). A turn is named by your prompt, else by what began it: a background task done (its summary), a ! command, a scheduled task, another session's message; beside it, its steps summed (read 12 · run 4 · net 1). A Claude subagent's steps sit under the call that started it. On top: what the agent waits on you for (a permission it asks, from keepane setup's hook), and what still runs in the background, until its task says it is done, the agent stops it or the agent starts again; the failures of the latest turn are counted, a hook's apart. The latest turn is open, the earlier ones a line each (e opens every one); after a turn, how long the agent has waited for you. The tab shows the bottom, the latest step, as more come (g the top, G back). A line is written when what it tells is over, so a model call shows once its reply is in: while a turn runs and no tool does, the model is at work since the last step (thinking). keepane trace-pane -t <pane> prints the same as a tree, -J as JSON (each step's kind, name, what it was given, start and end in milliseconds, parent, why it failed, background; and what it waits for).

Only agents in keepane's panes are read. An agent elsewhere (another terminal, an editor) working in the same directory at the same time writes to the same folder, and its transcript is counted with the pane's.

Messages and changes to panes are written to an event log, %LOCALAPPDATA%\keepane\events\<socket>\2026-09-26.jsonl, kept for 30 days (event-log, event-log-days, event-log-max). list-tasks, show-task, trace-message and list-events read it. When the server stops, messages not yet delivered are dropped, and the log says so. Pane names and work modes are saved with the session. The design in detail: docs/design/mailbox.md.

Install

keepane keeps its files (logs, the event log, saved sessions, pane history) in its data directory: %LOCALAPPDATA%\keepane on Windows, ~/.local/share/keepane on Linux, ~/Library/Application Support/keepane on macOS. The paths below are written the Windows way.

Linux and macOS

With Homebrew (macOS on Apple silicon or Intel, Linux x86_64):

brew install newdee/tap/keepane

Or by its short name, the tap added and keepane trusted once (Homebrew 6 and later load a formula of a tap not their own only once it is trusted; brew trust --formula trusts this one, not the whole tap):

brew tap newdee/tap
brew trust --formula newdee/tap/keepane   # Homebrew 6 and later
brew install keepane

brew upgrade keepane takes a new version. Or from the releases page: keepane-v<version>-linux-x86_64.tar.gz (a static build that runs on any x86_64 Linux), keepane-v<version>-macos-aarch64.tar.gz (Apple silicon) or keepane-v<version>-macos-x86_64.tar.gz (Intel). Unpack it and put keepane on your PATH:

tar xzf keepane-v<version>-linux-x86_64.tar.gz
install keepane-v<version>-linux-x86_64/keepane ~/.local/bin/

Or build it (below). The server listens on a socket in $XDG_RUNTIME_DIR/keepane-<uid>/ (else /tmp/keepane-<uid>/), a directory only you can open. keepane startup on starts the server at login (a launchd agent on macOS, a systemd user unit on Linux; see below). keepane update and the Windows Terminal profile are Windows matters: on Linux and macOS, update keepane the way you installed it (brew upgrade keepane, or the releases page; keepane update says which).

Windows

keepane needs Windows 10 1809 or newer (for ConPTY) and nothing else: the C runtime is in keepane.exe, so no Visual C++ redistributable is needed. From the releases page:

  • keepane-v<version>-windows-x86_64.zip holds one folder, keepane-v<version>-windows-x86_64, with keepane.exe in it. Unzip it and put that folder on your PATH. No administrator rights needed.
  • keepane-<version>-windows-x86_64.msi installs into Program Files for every user and puts keepane on the system PATH; it uninstalls from "Apps & features". It needs administrator rights (unattended: msiexec /i keepane-<version>-windows-x86_64.msi /qn).
  • keepane-<version>-windows-x86_64-user.msi installs for you alone, into %LOCALAPPDATA%\Programs\keepane, and puts it on your PATH. Neither it nor keepane update needs administrator rights, so both work over SSH.

Scoop installs the zip straight from the manifest in this repository, with no administrator rights:

scoop install https://raw.githubusercontent.com/newdee/keepane/master/packaging/scoop/keepane.json

Over SSH, Windows 11 does not let the session go through a junction made without administrator rights, and Scoop's current folder is one: the shim fails with "The path cannot be traversed because it contains an untrusted mount point". Point Scoop's shims at the version folder instead:

scoop config no_junction true
scoop reset keepane

Scoop updates an app only while none of its programs runs ("Running process detected, skip updating."), and keepane's server always does: a bare scoop update keepane changes nothing. keepane update steps aside for it: a copy of keepane outside Scoop's folder saves the sessions, stops the server (the programs in the panes start again, as with restart-server), runs Scoop, and starts the server again with the sessions; it writes what it did to update.log beside server.log.

Over SSH, the per-machine MSI's permission prompt appears on a desktop where nobody can answer it; keepane update says so and stops. Use the per-user MSI, the zip or Scoop there.

WinGet manifests for the MSI are in packaging/winget/ (validated with winget validate); winget install newdee.keepane works once they are merged into winget-pkgs, and until then winget install --manifest packaging/winget/manifests/n/newdee/keepane/<version> from a clone does the same. See packaging/README.md.

From source

Building from source needs Rust 1.88 or newer:

cargo install --git https://github.com/newdee/keepane --locked   # latest master
cargo install --path .                                         # a local clone

To build the Windows MSI, the script downloads WiX for the occasion if it is not installed:

cargo build --release
pwsh -File installer/build-msi.ps1        # target\keepane-<version>-windows-x86_64.msi

Everyday use

Splitting a shell into panes, typing one line into all of them with set sync, moving with h/j/k/l, zooming, the pane menu, a variable for every pane shown with C-b e, the window picker, detaching and attaching again

A deploy finishes in a window nobody is looking at, the status line marks it with #, C-b M-n jumps there, a failing command leaves its pane and exit code behind, and a popup shows the window list

C-b w opens the chart: keepane on top, then the sessions, the windows and the panes in open boxes; h, j, k and l move through it, a opens every node at once, v turns it into the tree and the plain list

On Windows keepane passes keys on in Windows' own win32-input-mode, so PSReadLine chords, Ctrl+Space, Shift+Enter, arrows with modifiers, IME input, and vim and htop under WSL all work. It runs in Windows Terminal, the classic console, VS Code's terminal and other Windows console hosts. On Linux and macOS it reads what the terminal sends (xterm keys with their modifiers, bracketed paste, SGR mouse) and passes it on as a terminal would, so it runs in any xterm-compatible terminal and over SSH.

keepane                      # the session used last; else resume; else new
keepane new                  # always a new session
keepane new -s work          # named session
keepane new -d -s bg htop    # detached session running htop
keepane ls                   # list sessions
keepane attach -t work       # re-attach (works from a different terminal window)
keepane send-keys -t work "git status" Enter
keepane capture-pane -p -t work   # print what the pane shows (-S -200 adds scrollback)
keepane kill-server

As in tmux, a command name can be any unambiguous prefix: keepane att, keepane lsp, keepane splitw -h. keepane kill is refused, because four commands start that way. keepane list-commands prints them all, and docs/tmux-parity.md sets them against tmux's, command by command and key by key.

Several panes at once: keepane split-window -N 3 makes three more and tiles the window (-d keeps the focus where it is). A window too small for all of them keeps the ones that fit and says how many it made.

In a session, press the prefix Ctrl+b, then a key from this table:

Key Action
c / n / p / Tab / 0-9 new window / next / previous / last / select by index (' asks for an index, for windows past 9)
, / & rename / kill window
% / " split left-right / top-bottom
h j k l or arrows / o / ; move between panes (vim keys) / next pane / last pane
H J K L, Alt+arrows / Ctrl+arrows resize the current pane by 5 / by 1
Shift+arrows when the window is bigger than this terminal (window-size took another client's), pan this client's view by 5 rows / 10 columns; the view follows the cursor again at the next key (down to the window's bottom when the cursor shows there, so the lines under it, such as an agent's status lines below its input box, are not the part cut off)
(moving, resizing, n / p and { / } repeat: after the prefix, keep pressing the key for half a second, repeat-time)
S toggle synchronize-panes (type into every pane of the window; S flag on the status line)
C-s / C-r save every session, each into its own file / restore saved sessions (see Resume)
z zoom (toggle) the current pane; moving to another pane of the window (h j k l, q and a number, ;) keeps the zoom and takes it there, until z again (set -g keep-zoom off unzooms instead, as tmux does)
x kill the current pane
u bring back the pane or window killed in the last 10 seconds (undo-kill)
C-t show when each command ran, how long it took and how it ended, at the end of its line (pane-timestamps)
/ browse what panes printed, by pane and day (choose-history)
y copy what the last command printed, without the prompt or the command, to a paste buffer and the clipboard (copy-output)
Y pick a command any pane ran, newest first: go there, copy what it printed, run it again (choose-marks)
@ pick a machine ssh reached: go to the pane on it, or connect in a new window or a split (choose-ssh, see SSH machines)
F put a label on every path, web address and git hash on screen; type one to copy that thing, in capitals to open it (hints, see below)
e show the environment every pane gets, in colour: what set-environment set, and what keepane sets itself (show-environment; see Environment)
{ / } swap pane with previous / next
q show the pane numbers (with the name and work mode, %name · ai, under them); press one to go there at once (past 9, a second digit straight after goes on from there: 1 2 is pane 12)
Space / M-1…M-5 / E cycle the layout / pick one (even-horizontal, even-vertical, main-horizontal, main-vertical, tiled) / even out the panes next to this one
C-o / M-o rotate the panes through the layout
! break the pane out into its own window
m / M mark this pane / clear the mark (join-pane takes the marked one)
T / f name this pane / find a window by name or title
[ / PgUp copy mode (see below)
# / - / = list paste buffers / delete the newest / pick one to paste
t / ~ / r clock, and under it the date (and UTC), other places' time (clock-mode-zones), what waits for you (agents, windows; see below), the pane (program, folder, branch, how long it has run and been quiet), its last command (how long, how it ended; a long folder or command shortened with … so the rest fits), its agent (model, cost, context) and the machine, then the month with today marked when it fits (clock-mode-info off: the time alone; clock-mode-style 12, clock-mode-colour); below, something that moves with the machine (see below); p shows the phone page's QR code, q leaves it / recent messages / redraw
] paste the clipboard
: command prompt (:split-window -h -c C:\src, :set mouse off, ...; Tab completes the command, its flags, a -t target and option names; ↑ / ↓ or C-p / C-n bring back the lines run there before, the last 100, until the server stops; show-prompt-history lists them, clear-prompt-history forgets them)
d detach
? list key bindings. This and other output of more lines than the window (:show-messages, :show-prompt-history) opens at its end, as tmux's view mode does, and scrolls: ↑ ↓ or j k, PgUp PgDn, g G, the wheel; / ? search it (the hit in inverse), n N go on; any other key closes it
(wait) after the prefix, a key not pressed within half a second brings up a panel of what the keys do, by group (panes, windows, sessions, tools, and keys you bound yourself); the key then works as ever (prefix-hint, prefix-hint-delay)
s / w pick a session / a window, w down to every pane. By default a chart: keepane centred on top, the sessions on the row under it, then the windows of the session you are on, then that window's panes, each row spread across (a row wider than the screen scrolls, ‹ › at its ends), each an open box in its kind's colour (a session blue, a window purple, a pane green, the selected one yellow; its name in the text's colour, the rest faint) with what it is in its top border (host, session, window, pane); h l or ← → move along a row and the rows under it follow, k or ↑ goes to the parent, j or ↓ to the current window or the active pane. a opens every node at once, each parent over its own; when that does not fit the boxes get narrower, then become one line each, then just their numbers, and what is still too wide scrolls to the selection (a again: only the branch). Paired with other machines (keepane link, below), a row of machines comes under keepane, this one first, each other machine's block its name (once it said it) over its address. A session is under the machine it is of and nowhere else: this machine's block has this machine's sessions only. Under a machine that gave this one --full are its sessions, windows and panes, and Enter on one goes into it; under one that only shares (link share, below) is what it shares (asked of it every 5 seconds while the chart is open; offline when it does not answer), and Enter on one of its panes opens a window watching it live (keepane link watch, below). On a machine's block, the key line says what it has here (has full, has 2 shared, has nothing); c connects it, x disconnects it (this machine stops asking it; it reads disconnected), R takes back what it has here and D forgets the pairing (both asked first). x and D on a session, window or pane of another machine ask first and say which machine it is killed on. s shares a session, window or pane of this machine with the paired machine (a menu asks which when there are several), or takes it back; shared ones read shared. v turns it into a tree of blocks, one a line (↑ ↓ the parent and the first child, ← → along the same level, - / + fold and unfold a session or a window), then the plain list (j k or arrows move, -/+ or Left/Right fold), then the chart again. In the tree and the list j k go line by line; in all three g G top/bottom, digits jump (every line you can pick is numbered; past 9 type both digits, 1 2 is line 12), Enter goes there, q cancels; f filters by a substring as you type, Enter keeps it and Esc puts the old one back; t tags the line, T clears the tags, x kills the tagged lines, or the current one; D (or Delete) kills them and also forgets a session's save, so that resume does not bring it back. On a session both ask first (y/n). set -g choose-tree-style tree (or list) opens it that way
( / ) switch the client to the previous / next session
D pick a client from a list and detach it
> / < pane menu / window menu (the letter in brackets runs the entry, Enter runs the highlighted one)
M-n / M-p next / previous window with an alert (see monitor-activity)

A keepane inside a pane (on a server, over ssh) has C-b as its prefix too, and this keepane takes it first. C-b C-b sends one C-b on, so C-b C-b c makes a window on the server. To work there a while, press F12: the pane gets every key, the prefix and the keys bound with bind -n too, and the status line says passthrough. F12 again gives the prefix back. It is the pane's own: the other panes keep the prefix, and clicking one of them works as ever. passthrough [-t pane] [on|off] does the same from a script; bind -n <key> passthrough picks another key (the one bound is the only key it lets through).

With a Chinese, Japanese or Korean input method on, a key that comes in its full-width form (【 for [, : for :, y for y) works as the key: after the prefix, in copy mode, in the pickers and menus, at a y/n question and in the dashboard. What is typed into a pane, or as text at a prompt (a window's name), stays as typed; a key bound in its full-width form is that binding.

Zooming, unzooming and moving the focus are animated, for 160 ms by default. Programs are resized once, to the size they end up at, so nothing waits for the animation. set -g animation off turns it off, and animation-time sets the milliseconds.

Under the clock (prefix t), in the rows the time and its lines leave, something moves with the machine and with keepane (clock-mode-animation):

  • pulse: a monitor. The heart beats at 60 a minute with the cores idle and 150 with them all busy, and once early for each message keepane delivers (at most four waiting); a network wave stands as tall as the traffic; a disk wave breathes faster and deeper the more the disks do; a system wave swings faster with the context switches and taller with the interrupts. Each trace has its figures beside it (♥ 92 CPU 35% 67W 61°C ✉ 2, NET ↓1.2M ↑80K 3.1k pkt/s, DISK r12M w0, SYS 48k/s 312 proc 4.3k thr). 67W is the CPU package's power; PWR 20W, what a battery gives while the machine runs on it; ✉ 2, the messages delivered while this clock is up.
  • matrix: falling characters. Faster with the cores, more columns with memory, cyan columns with the network, quicker flicker with the disks, stray magenta characters with the interrupts; each message delivered falls as a white drop headed by ✉.
  • bars: an equalizer with a bar for each core, then memory, the disks (read, written), the network (in, out), the temperature and a bar for each pane of the window by what it prints; then, where they fit beside those, messages (full on one, falling back), the CPU's watts, the battery's, swap, and context switches with interrupts. Each group labelled, peaks falling slowly.
  • fire: a flame for each core across the rows, as tall as the core is busy; its tip yellow, bright yellow or white as the CPU gets hotter; sparks with the interrupts; each message an ✉ rising through it.
  • starfield: a flight through stars, more of them the more processes run, faster (streaking, at a warp) the more the network carries; each message a comet with ✉ at its head.
  • sharks: a sea seen from above. A school of fish for each pane of the window (six at most), swimming faster the more the pane prints and turning more with the context switches; a shark hunting them, hungry sooner the busier the cores, longer with memory; all of it drifting with the network, the water glinting with the disks; each message a ripple with ✉ in it, the shark racing to it.
  • bonsai: a tree in a pot, growing through the day (a sapling after midnight, most of it by the morning, all of it by night), a limb for each pane (six at most), its leaves always stirring (quicker with the context switches) and shaking the more the pane prints; more leaves with memory, leaning in the network's wind; a leaf falling now and then, more with the disks; each message an ✉ falling from a leaf.
  • sea: a moonlit sea. The moon crosses the sky with the hours (rising on the left at 18:00, highest at midnight, setting at 06:00; pale by day); stars by night, more with memory, twinkling with the context switches; waves choppier and quicker the busier the cores; the moon's path on them glittering with the network; a boat for each pane, faster the more it prints; each message an ✉ drifting ashore.
  • cat: a cat asleep, breathing quicker the busier the cores, a z rising with each breath; its tail swinging with the network, an ear flicking with the disks; a ball of yarn rolling past, faster the more the window's panes print; each message an ✉ falling beside it, which wakes it for three seconds.
  • dino: a dinosaur running across a desert, faster the busier the cores (its score, the distance, top right), jumping every cactus; more cacti the more panes the window has; clouds drifting over with the network; each message an ✉ falling to it, and a heart while it is glad of it.
  • penguins: an ice shelf with the sea beyond, a penguin for each pane waddling on its own stretch, sliding on its belly while its pane prints a lot; the sea rolling quicker with the cores, snow with the network, an aurora brighter with memory; each message a fish leaping out of the sea onto the ice, its ✉ over it.
  • synthwave: a neon grid running towards you, faster the busier the cores, under a striped sun setting on the horizon (its stripes sliding with what the panes print), mountains either side taller with memory, stars twinkling with the network; each message a meteor across the sky with ✉ at its head.
  • fireworks: a city at night (more windows lit the more memory is used) under rockets going up, more of them the more the panes print, bursting into rings of sparks that fall and fade, bigger the busier the cores; each message a rocket twice the size with its ✉ where it bursts.

The lines over it end with keepane's own: its sessions and panes, and the messages it has delivered since it started.

In pulse, matrix and starfield, and in the shark's eyes and the bonsai's leaves, the colour goes from green through yellow to red with the CPU's temperature, or with the cores' load when there is no temperature; the bars are green at the bottom, yellow higher up and red at the top. random (the default) picks one of the 13 each time the clock is put on a pane, never the one it had before; cycle takes them in turn; a name sets that one; off, or animation off, leaves the clock still. (aquarium, life, donut, weather, hourglass, orbits and radar were taken out in 0.46; from 0.77 a config that still names one is told so, as with any other name.) Under a clock, / turns to the next kind and ? to the one before, its name shown for a second; that holds until the clock goes, the option is not changed (/ starts one under clock-mode-animation off, none under animation off). The clock stays until q (tmux's goes at any key); the prefix still works under it. It is drawn in the 16 colours a theme sets (pane-colours; the terminal's own when the theme sets none), so each theme colours it. The machine is read twice a second, only while a clock is on screen. A figure the system does not give is left out, never made up: macOS gives no interrupts and no power, and counts the context switches and threads of the processes you may look into, not the whole system's; the temperature comes from a real CPU sensor only (Linux: thermal zones and hwmon; Windows: LibreHardwareMonitor or OpenHardwareMonitor while one runs, since Windows' own ACPI thermal zone is a fixed figure on many machines; macOS: none). The CPU's power is its own meter (RAPL): Windows reads it for anyone, where the CPU has one; Linux lets only root read it on most systems (/sys/class/powercap), so there it shows only when readable.

Right under the date (and the other places), a line in yellow says what waits for you, in every session: each agent that waits on you (its permission hook ran pane-wait; work:1.0 claude waits, until it goes on), then each window the status line marks, which is never a session's current window (bell, message, activity, silence). With nothing waiting there is no line.

While the phone page is served (keepane web), the clock's last line says p: phone page: p puts the page's QR code over the clock, white on black whatever the theme, for a minute or until another key. The code carries the page's key, so it is not left on a screen nobody watches. Without a page, p says how to start one.

clock-mode-look draws any of them in a set of characters instead of its own: dots (· • ●), blocks (░ ▒ ▓ █) or binary (1 0). Each cell takes the character with as much ink as it had: how much of the cell its own character covered, and how bright it was. The colours stay, and so do the figures, the names and each message's ✉. plain, the default, keeps its own characters.

The clock over a pane running a build, seven times: a monitor whose heartbeat speeds up and slows down with the CPU, falling characters, bars for each core, memory, the disks, the network and the pane's output, a moonlit sea drawn then in dots, and a cat asleep that a message wakes, a dinosaur running a desert and a neon grid under a striped sun

The pulse monitor: the heartbeat, the network, the disks and the system as traces, each with its figures The bars: a bar a core, memory, the disks, the network, the temperature and each pane's output, each group labelled

Copy mode, the keys used most:

  • Moving: h j k l or the arrows; w b e by word; 0 ^ $, H M L, { }, g G jump; [ ] go to the previous / next command the shell ran, where it was typed. 0 and $ go to the ends of the line the program printed, across the rows a long one wrapped onto; $ to its last character, not the blanks after it. f and a character go to the next one on the row, F back to the one before, t T stop next to it; ; and , do it again, the same way or the other way.
  • Paging: PageUp / PageDown or C-b / C-f; C-u / C-d by half a page. Since C-b is also the prefix, C-b C-b pages up in copy mode. A number repeats a key, such as 3j.
  • Selecting and copying: Space or v starts a selection, V selects whole lines (V again: none), C-v makes it a rectangle, Enter or y copies to a paste buffer and the Windows clipboard.
  • Searching: / searches, ? searches backwards, n / N go to the next hit; ↑ / ↓ at the / prompt bring back what was looked for before, the last 100; q leaves.

A script does the same with send-keys -X <command>, with tmux's command names.

The mouse selects a pane, drags a border to resize, and switches windows from the status line. The wheel enters copy mode and scrolls back on the normal screen, sends arrow keys to full-screen programs, and is passed through to programs that ask for mouse events; send-keys WheelUp (or WheelDown) sends a program what the wheel would, from a script (nothing on the normal screen, where the wheel scrolls keepane's own history). Drag to select text; it is copied to the Windows clipboard on release, wherever the pointer is let go, and a right click pastes the clipboard into the pane, as the terminal itself would. Dragged to the pane's top or bottom row, or past it, the pane scrolls while the pointer stays there, so a selection can take more than the screen holds. A selection copies the columns it covers: a Chinese character, two columns wide, is copied whole.

C-b F (hints) puts a label of one or two letters on every path, web address and git hash in the panes on screen: a compiler's src/main.rs:12:5 or App.cs(12,5), https://…, af9af7e. Typing a label copies that thing to a paste buffer and the clipboard (a path without its line). Typing it in capitals opens it: an address in the browser, a path at its line in VS Code when code is on the PATH, else in $VISUAL or $EDITOR in a new window (vim +12 src/main.rs), else in what the desktop opens it with. A relative path is taken from the pane's directory. Escape puts the labels away. A bare name with no slash and no line number (notes.txt) counts only when that file is there, so prose is left alone; something the terminal wrapped onto the next row is not found.

set -g hint-open '<command>' opens paths your way: a keepane command in which {file}, {line} and {col} are put as they are, so quote a path that may hold spaces with single quotes:

set -g hint-open "new-window hx '{file}:{line}:{col}'"
set -g hint-open "run-shell 'idea --line {line} {file}'"

Command times and history

Command times at the end of each command's line, one failing; C-b Y listing the commands the panes ran; the history picker listing pane positions and days; a day opened in the pager; / searching every day; a pane closed by mistake coming back with C-b u

A PowerShell, bash or zsh pane reports each command it runs through the prompt hook keepane starts it with (after your own ~/.bashrc or .zshrc, whose prompt it leaves as it is). macOS's own /bin/bash (3.2) does not say when a command starts (PS0 came in 4.4); keepane takes the moment Enter went into the pane instead, so a time there counts from the key rather than from the shell. C-b C-t (or set -g pane-timestamps on) shows, at the right end of the line the command was typed on, when it started, how long it took and whether it failed:

PS C:\src> cargo build                                     14:03:22 41s ✓
PS C:\src> cargo test                                      14:04:10 12s ✗

The time goes in the blank end of the line and changes neither the pane's width nor what the program printed; copy mode and capture-pane do not include it. A line without room for it goes without. keepane list-marks prints the same for a script; list-marks -J as JSON, with the lines each command takes (what was typed may wrap, a prompt may take two lines) and the command itself. On the phone, When each command ran (in the view menu) shows the times in a column to the left.

Knowing where each command starts and ends, C-b y (copy-output) copies what the last one printed (the lines between it and the next prompt, at most 4 MB) to a paste buffer and the clipboard: a failing test's output, ready to paste into an issue or an agent. keepane copy-output -p -t %3 prints it instead, for a script. In copy mode, [ and ] go from command to command.

C-b Y (choose-marks) lists the commands every pane's shell ran that its screen still holds, newest first: how each ended (✓, ✗), when, how long, in which pane. Enter goes to one, in copy mode at its line; y copies what it printed, as C-b y does for the last one; r runs it again in its pane (only while that shell is at its prompt); f filters the list (✗ for the failed ones).

A test fails in the left pane; C-b y copies what it printed; send-message hands it to the agent pane on the right, which fixes the code and says it is free; the test then passes

A test fails; C-b y takes what it printed; one message hands it to the agent beside it (keepane send-message --to %claude "fix this: $(keepane show-buffer)"), which gets it when it is free. (The agent in the recording is a stand-in that writes an agent's transcript; any agent set up with keepane setup works the same way.)

SSH machines

C-b @ (choose-ssh) lists the machines you reach with ssh, in a box: the ones a pane is connected to now first (a green dot and the pane), then by when you last connected. Each row has its name, who and where (root@10.0.0.5:2222), when, how many times, and where it was found when no pane has connected to it yet (config, seen, history).

The ssh box over a pane: a machine connected to now with a green dot and its pane, others by when they were last used, the keys on the box's lower edge

Enter goes to the pane connected to it, else opens a window named after it that runs ssh; s connects in a split beside the pane, y copies the command, d takes the machine off the list, f filters.

The list comes from four places: each ssh keepane sees start in a pane (one use each, with its time), the Host lines of ~/.ssh/config, the names in ~/.ssh/known_hosts (hashed ones say nothing), and, once, the ssh commands in the shells' history files. The used ones are kept in %LOCALAPPDATA%\keepane\ssh-hosts.json: names, users, ports, times and counts. No password or key is read or kept. keepane ssh-hosts prints the list (-J as JSON, which the MCP tool list_ssh_hosts gives agents); #{pane_ssh_host} says where a pane's ssh goes, and the dashboard shows it as what the pane runs.

A shell started with a script or command of its own (pwsh -File, bash -c) is left as it is, hook and all; that script can install the hook itself: Invoke-Expression (keepane __shell-hook | Out-String) in PowerShell, eval "$(keepane __shell-hook)" in bash.

fish gets the hook too (fish 4 marks its commands itself; keepane adds the rest), and so does a pane started as wsl.exe (default-shell wsl, or wsl.exe -d Ubuntu with no command of its own): keepane starts the WSL user's own shell, bash, zsh or fish, reading the same start files a login shell would, then the hook. Such a pane keeps the distribution's history, and set-environment's variables reach it as they reach a PowerShell (through WSLENV). Other shells report their commands with the sequences Windows Terminal and VS Code read too (OSC 133). For bash over SSH on another machine, or a WSL shell started from inside a PowerShell pane:

PS0='\e]133;C\e\\'
PROMPT_COMMAND='printf "\e]133;D;%s\e\\\e]133;A\e\\" "$?"'

The panes' output can also be saved to disk (log-history, on by default): one text file per pane position per day, at %LOCALAPPDATA%\keepane\history\<session>\<window>.<pane>\2026-09-25.log, for 30 days (log-history-days), at most 20 MB a day each. A line is written when it scrolls off the top of the pane, so a progress bar or a prompt being edited leaves its final text; full-screen programs such as vim leave nothing; what is still on screen when the pane closes is written then. Each reported command gets a line of its times before it (── 14:03:22 · 41s · ✓ ──).

C-b / (choose-history) lists the pane positions that have history, with their days. Enter on a day opens it in a viewer in a popup. The viewer starts at the end and moves like less: j k, Space b, g G, / ? to search, n N to repeat, [ ] to jump from command to command, q to quit. keepane view FILE opens any file in it (-n LINE at that line, -s TEXT with that search set). set -g log-history off stops the logging.

/ in that list looks through every day of every pane at once (the newest day first, 500 lines at most): the lines that hold it are listed with their day and pane, and Enter opens the viewer at one, its search set. keepane find-text -H pattern does the same for a script, beside what the panes' screens hold: work:0.1 2026-10-21:1234 error: ….

A pane or window closed with kill-pane or kill-window (C-b x, C-b &) is kept for 10 seconds with its programs still running. C-b u (undo-kill) puts it back where it was. After that it is gone as before. undo-kill-time sets the seconds; 0 ends it at once, which is what you want when you kill something to free a port or a file. The last pane of a session is not kept, because the session ends with it.

Resume after a reboot

A session of three panes: git status, a build named builder, a server log; C-b C-s saves it; the server is stopped as a reboot stops it; a plain keepane started again brings back the panes, their names and folders and what they showed

Every session is saved to its own file under %LOCALAPPDATA%\keepane\sessions whenever its shape changes (windows, panes, layout, names, start commands and directories) and when the server exits; a server started with -L NAME keeps its own in sessions-NAME beside it, so one never brings back another's sessions. A reboot or a crash does not lose that file. kill-session puts it aside: the session does not come back by itself at the next start (nor with a bare keepane), resume or resume NAME still brings it back, and list-saved says it was killed. A session whose last program exits (you typed exit in its last shell) forgets it 10 seconds later, unless the machine is shutting down; D in C-b w or delete-saved forgets one by hand. So:

keepane resume              # bring back every saved session, attach to the first
keepane resume work         # bring back (or just attach to) the session "work"
keepane list-saved          # what can be resumed, newest first
keepane delete-saved old    # forget one
keepane save-session -a     # save each session to its own file now (prefix C-s)

A bare keepane resumes too: with sessions running it goes into the one used last, with none running it brings back every saved one (not those killed by hand) and goes into the one saved last, and only with nothing at all does it start a new one (keepane new always does). So starting keepane again and again does not pile up empty sessions that come back on the next resume.

Resuming recreates the pane tree, puts back the last save-history lines each pane had on screen (500 by default; set -g save-history all keeps the whole scrollback, colours included) and starts each pane's original command in the pane's last known directory. What the programs themselves were doing does not come back; no multiplexer can do that. Saving happens by itself: the tree whenever it changes, the pane text every 30 seconds, and everything once more when Windows shuts down, restarts or you log off (the server holds the shutdown up for the moment that takes), or when the server is sent SIGTERM or SIGHUP on Linux and macOS. A server that starts brings every saved session back by itself, however it was started (keepane, keepane new -s x, at logon), so no session is made beside saved ones not running: keepane new -s work with work saved says it exists (-A attaches to it). set -g restore-on-start off leaves that to resume; set -g autosave off turns saving off; sessions-dir moves the files.

Sessions, windows and panes keep their numbers ($1, @3, %4) when they come back after a restart. The server keeps its counter in the sessions directory (next-id), so a number is never given to a second pane on that machine: a script or another machine that holds %4 finds that pane or none. A session killed and resumed while the same server runs gets new numbers, and so does one whose number is already taken.

Each PowerShell, bash or zsh pane keeps its own command history (what Up brings back), in a file under the sessions directory, so a resumed pane has what it ran and not what every other pane ran. A new pane starts with a copy of the history of the pane it came from (the one split, or the one in use for a new window), else of the shell's own history file. Files no pane or saved session refers to go after log-history-days.

A message delivered to a pane in shell mode is a command there too, and goes into that history with its header in front (<# keepane #12 from %builder #>). keepane shell-history -t %3 reads the history back, each message marked (✉ #12 %builder cargo test); -c leaves the messages out, -m lists instead every message sent to the pane in any mode, from the event log, with how it went; -n 20 shows the last 20.

To have all of that happen by itself when you log on:

keepane startup on          # start the server at logon and restore every saved session
keepane startup status      # what is registered
keepane startup off         # stop doing that

On Windows this writes one value under the per-user Run registry key (no administrator rights, nothing in Task Scheduler), running the server through conhost --headless so no console window appears at logon. On macOS it writes a launchd agent, ~/Library/LaunchAgents/tech.dfine.keepane.plist; on Linux a systemd user unit, ~/.config/systemd/user/keepane.service, enabled for default.target. Both keep the PATH, SHELL and locale that startup on ran with, so the panes find what your shell finds. Neither starts a server when written: the next login does. On Linux the server stops at logout (it saves first) unless loginctl enable-linger keeps your user manager running, and then it starts at boot too; where systemd does not run (a container, WSL without it), startup on says so and writes nothing. After a reboot, keepane attach finds everything as it was. The phone page (keepane web, below) comes back too when it was on, served the same way (add -k so that its code stays the same); until the network is up after logon, it is tried again every 10 seconds.

The logon command runs keepane by its full path, and so does the Windows Terminal profile below. When an update puts the new keepane in a folder of its own (Scoop with no_junction, a folder per version, Homebrew's Cellar), the first keepane you run afterwards moves both to itself and says so, a line for each; it does the same when the old folder is gone. A keepane never takes them from a newer one. On macOS and Linux, startup on registers the name your PATH finds (Homebrew's bin/keepane, which each upgrade points at the new version) rather than the file in the Cellar.

Upgrading: installing a new keepane does not replace the server that is already running, which keeps your sessions and is still the old program.

keepane version          # this keepane, and the server's version when it differs
keepane update --check   # is there a newer release?
keepane update           # Windows: install it the way this one was installed (MSI or scoop)
keepane restart-server   # move every running session to a server of this version

restart-server saves the running sessions, stops the old server, starts one of this version and restores exactly those sessions, layout, history and directories included; terminals attached to it attach again by themselves (from 0.10 on; an older server's terminals are detached, and keepane attach takes them back). Run from inside a pane it finishes outside the pane and writes what it did to %LOCALAPPDATA%\keepane\restart.log. Options and key bindings come from the config file again, as after kill-server: ones typed with set/bind since are not carried over (the old server cannot tell them from its defaults, and copying all of them would pin the old version's defaults on the new one). While a terminal is attached to a server of another version, its title says so. update downloads the MSI, checks it against the SHA-256 published beside it, and hands it to Windows Installer; nothing is ever installed in the background.

Once a day the server asks GitHub for the latest release's version (one request to api.github.com, with curl, sending nothing about you or your sessions), and when it is newer the status line says so (⇡ 0.19.0, the #{keepane_update} format variable) and show-messages says how to get it. What it heard is kept in the data directory, so a restarted server does not ask again that day. set -g update-check off (or the environment variable KEEPANE_NO_UPDATE_CHECK) stops it.

Tab completion in PowerShell, bash, zsh and fish (command names, each command's flags, -t targets from the running server, and option names and values after set / show; aliases like splitw and prefixes like split-w count as the command they stand for) comes from a completer the program prints; one line loads it. In PowerShell it also covers a tmux alias of keepane. Windows PowerShell 5.1 does not ask a program's completer about words starting with -, so there flags complete in PowerShell 7 only. Homebrew installs the bash, zsh and fish ones itself.

keepane completion powershell | Out-String | Invoke-Expression   # $PROFILE
eval "$(keepane completion bash)"                                # ~/.bashrc
source <(keepane completion zsh)                                 # ~/.zshrc, after compinit
keepane completion fish > ~/.config/fish/completions/keepane.fish

Inside keepane, Tab at the : prompt completes the command name, its flags once a - is typed (an alias or a prefix counts as its command; a flag already given is not offered again), a target after -t, and after set / show the option's name (abbreviations too: sync, mon-act) and then its value when it is one of a few (on/off, top/bottom); several candidates are typed as far as they agree and listed in the prompt.

PowerShell's Ctrl+D does nothing by default (bash's exits), so it does not close a pane either. To have it exit on an empty line, add to $PROFILE:

Set-PSReadLineKeyHandler -Chord Ctrl+d -Function DeleteCharOrExit

And to have keepane in the Windows Terminal dropdown:

keepane windows-terminal install    # a "keepane" profile that attaches to (or starts) the session "main"
keepane windows-terminal status
keepane windows-terminal remove

This is a profile fragment, one JSON file of keepane's own under %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\keepane\; Windows Terminal merges it in, settings.json is never touched, and the profile keeps its identity across reinstalls so the font or colours you give it stay. Every tab opened from it joins the same session, as tmux new -A -s main would.

A pane's directory follows its shell's cd, with nothing to set up: PowerShell (pwsh or Windows PowerShell), bash, zsh, fish and a wsl.exe pane's shell are started with a prompt hook that reports the directory after every prompt (an invisible OSC 9;9 or OSC 7; your own prompt, oh-my-posh and the like included, is left as it is), and for cmd.exe, sh and other programs keepane reads the process's own directory. A shell that announces its directory itself (OSC 9;9, quoted or not, or OSC 7; from WSL, /mnt/<drive>/... maps back to a Windows drive) is believed first, and keepane set-cwd (no argument: the directory you run it from) sets it by hand.

list-panes shows the recorded directory, and #{pane_current_path} puts it on the status line.

Using it from an AI agent

An agent in a pane sends and takes the same messages as anything else. Two things make that work: a hook that runs keepane pane-ready -q when the agent finishes a turn (so the pane counts as ready in ai mode), and keepane mcp, an MCP server (stdio) offering the commands above as tools. It takes the pane it serves from KEEPANE_PANE, so what the agent sends goes out with that pane as the sender.

keepane setup shows, for each agent it knows, whether it is on this machine and whether its hook and keepane's MCP server are set up. keepane setup <agent> prints what that agent needs; --install does it, each file backed up first and only keepane's entries added:

Agent setup word Hook (session start, turn end) Waiting hook MCP server
Claude Code claude SessionStart, Stop in ~/.claude/settings.json Notification (permission_prompt|elicitation_dialog) claude mcp add --scope user
Codex codex SessionStart, Stop in ~/.codex/hooks.json PermissionRequest codex mcp add
Gemini CLI gemini SessionStart, AfterAgent in ~/.gemini/settings.json Notification mcpServers there
Cursor CLI cursor sessionStart, stop in ~/.cursor/hooks.json none ~/.cursor/mcp.json
opencode opencode a plugin, ~/.config/opencode/plugins/keepane.js, on start and session.idle none mcp in opencode.json
pi pi an extension, ~/.pi/agent/extensions/keepane.ts, on session_start and agent_end none none (pi takes no MCP server; it sends with keepane in its shell)

Each runs keepane pane-ready -q, which is quiet outside keepane and ignored in panes not in ai mode. When Cursor's stop hook says the person broke the turn off (status aborted), the message it worked on ends unfinished, as Codex's transcript says it. It reads what the hook gives it on standard input (a second at most; nothing when run by hand): the session, its transcript and its model. That transcript is then the pane's agent's, read wherever it is (a Codex session resumed from weeks ago), and no other file in its directory is taken for it (another program's session there); the model shows from the first moment, before the transcript says one. Without a hook, keepane guesses as before: the agent of that kind started last in that directory.

Codex and Cursor write no word of a question they ask you, so keepane reads their screens for it, with herdr's rules: Codex's title saying "Action Required", or "press enter to confirm or esc to cancel", "enter to submit answer" or "allow command?" in its last lines; Cursor's "waiting for approval" or "run this command?". It is a wait as the waiting hook's (the Trace, the clock, done-events), over when the screen stops showing it. Cursor's "ctrl+c to stop" in its last lines is Cursor at work, and the pane is free again two seconds after it goes, with no hook, unless keys or a message went in after it was last seen (a turn its stop hook has ended, and the next one not drawn yet). The design: docs/design/agent-accuracy.md.

The waiting hook runs keepane pane-wait -q when the agent asks you something: a permission, or a question (Claude Code tells it once the question has waited about six seconds). It is told as done-events wait (below). Set up before 0.52.0? Run setup <agent> --install again: it adds what is missing. Codex's notify holds one program only and is left alone; Codex runs a new hook once you trust it (/hooks in Codex). A file that is not plain JSON (comments, say) is left alone, and setup says what to add by hand. These follow each agent's documentation; Claude Code is the one checked end to end. Writing the hook yourself, leave the program path unquoted (or write & "C:\path\keepane.exe" pane-ready -q): an agent on Windows may run hooks in PowerShell, where a quoted path followed by arguments is a syntax error. Any other agent works the same way if it can run a command at the end of each turn and use an MCP server over stdio; run keepane set-work-mode ai in its pane before starting it.

Codex (0.160 and later) and pi (1.0 and later) draw in the alternate screen by default, as vim does: what they print never reaches the scrollback, in keepane, in tmux or in any terminal, so there is no history to scroll back to. The wheel (and a drag on the phone) still scrolls them, through their own view. To keep their history in the pane instead, run them inline: for Codex, alternate_screen = "never" under [tui] in ~/.codex/config.toml (or codex --no-alt-screen); for pi, "tuiMode": "regular" in ~/.pi/agent/settings.json.

A message for an ai pane whose agent has never said it is free (since it started) waits: send-message says so, with the setup that adds the hook; the dashboard and the phone page say it too (#{pane_unheard}). For Claude Code, Codex and pi keepane also reads the agent's transcript (as for what it costs, every 2 seconds): a turn over there frees the pane with no hook, about 3 seconds late at the most, and a turn the person broke off (Esc), when no hook runs, frees it too, its message ending unfinished. The hook says it at once.

The 26 tools:

Tools For
whoami, list_panes its own pane, and every pane: address, name, mode, free or busy, inbox, program, status
send_message, reply, wait_message, current_message send a message, answer the sender, take the next message within a turn, see the message being worked on as keepane recorded it
list_messages, trace_message, drop_message, move_message the inboxes, and what became of a message (a shell command's output included)
create_session, create_window, split_pane, rename_pane, kill_pane make panes (each with a name, a mode and a first message), name any pane, close any pane
set_status, set_work_mode say what it is doing (the dashboard shows it); change its own pane's mode
list_tasks, show_task, query_events chains of messages, and the event log
wait_output wait until a pane prints a line holding a text (a server ready, a build failing), and get that line
list_links, link_info, read_screen, create_remote_pane, push_repo the machines paired with this one, what one of them is, what a pane (here or there) shows, a pane started there (kill_pane closes it), and the current branch's commits sent there

A pane made through MCP starts in ai mode when it runs claude, codex, gemini, cursor-agent or opencode, in shell mode when it runs pwsh, powershell, bash or zsh, and in normal mode otherwise, unless a mode is given. What an agent may start is limited to agent-commands (pwsh powershell claude codex on Windows, bash zsh sh claude codex elsewhere), and how many panes it and the panes it made may make to agent-pane-limit (8). Claude Code asks you before each MCP call you have not allowed.

On your phone

Leave a build, a deploy or an agent running, and check on it from the sofa (the group chat is there too: see the end of this list):

keepane web

prints a QR code in the terminal. Scan it with the phone's camera (same network) and the browser opens a page that lists every pane, under its session and window (the directory most of a session's panes are in beside its name): its name large (else the title its program set, else the program), then the program under it and its directory when it is elsewhere, the last thing it printed (not a prompt) and how long it has been quiet; a dot for its state (an agent or shell pane free green or busy yellow, exited red), the messages waiting in its inbox, and the window's alert marks from the status line (# printed, ! bell, ~ silent, with monitor-activity and friends on), so you can see which job finished without opening it. The speech bubbles in the header open the group chat (the number on them is what you have not read): the channels as a chat app lists them, the one last said in first, with its last line and what is unread; one opened (beside the list on a wide screen) shows each member's lines in its colour with its role and time, yours on the right, a rule at each day and where what you had not read begins, @name in that member's colour, and who is there (online or offline) under the people button. Type at the bottom to say something as you: a @ lists the members to name (↑/↓, Tab or Enter puts one in), Enter sends, Shift+Enter is a new line. Read-only, it is for looking. Tap a pane to see its screen, colours and all; keepane sends it again whenever it changes, so there is no refresh to wait for. Swipe across it for the next pane, or tap its title to pick one; swipe in from the left edge to go back to the list. A reload of the page keeps the pane that was open. What you type in the box at the bottom goes to the pane as you type it (deleting in the box deletes there too; an input method's word goes once it is chosen), and Enter is the Enter. The view menu (the sliders in the pane's bar) can make the box wait for Enter instead, for this device: Send then types what is in it, with no Enter after it (Send again, the box empty, is the Enter), or types and runs it. The history button beside the box brings back what you sent before (☆ keeps one at the top). The keys the phone keyboard lacks are in a row above it (Esc, Tab, arrows, more under ⋯; Ctrl+C and Enter stay in view at its end); Ctrl, Alt or Shift (any of them together), then a key of the row or a letter typed, sends it with them (Shift then → is Shift+Right). The ⋯ menu in the pane's bar, and a right click (a long press on a phone) on a pane in the list, split the pane, open a window (the phone opens the new pane; the computer's terminals keep looking where they were), rename the pane, its window or its session (a pane's name empty takes it away), close the pane or show its inbox (also a tap on a card's "queued" or "on #N" mark): the message it works on, each waiting one whole, to put first, up, down or delete (and undo), and the last few it finished. The view menu holds the rest: When each command ran adds a column with the time each command started (tap one for its date, how long it took and its exit code, and to copy the command or what it printed; see "Command times and history"). Under the screen is the session's status line, as the terminal draws it, in its colours, when all of it fits there; where it does not (a phone held upright), its button in the pane's bar (by the box in full screen) opens it from the side, nothing cut: the windows a row each, then each part of its ends as it is drawn. Tapping a window opens it. The window marked current is the one the page shows (the page keeps its own view; the terminal's current window stays as it was). Status line, in the view menu, hides it on this device; set -g status off hides it everywhere. A tap on a session or window folds it (the device remembers); its right click or long press renames it or folds every window of a session at once. The two buttons at the top of the list show it as a grid instead (the device remembers): a cell for each pane, two side by side on a phone held upright and more on a wider screen, each with the pane's state, name, inbox and window, and the last 4 lines it printed in the terminal's colours. Tap a cell to open its pane; a long press opens its menu. A pane wider than the phone wraps its long lines at the phone's edge (the view menu turns that off, for a full-screen program). Fit to this screen, in the same menu, sizes the pane to the phone: it fills its window and its session takes the phone's columns and rows, so a full-screen program (vim, htop, an agent's screen) draws for the phone. Meanwhile the computer and any other phone see that session at the phone's size too (a session has one size; the page and the status line say so); leaving the pane, going back to the list or putting the phone away gives it back its size, and so does keepane when no phone has shown it for 10 seconds. Everything runs on the computer; the phone only shows and types. "Add to Home Screen" makes it open like an app.

On a shell or ai pane, the envelope beside the box sends what is in it as a message instead of typing it: into the pane's inbox, from the user, to wait its turn like any other (as send-message does). The ⋯ menu and a card's menu set what a pane does with the messages it gets: normal leaves them waiting, shell runs them at its prompt, ai hands them to its agent. The view menu also finds text in the output (the lines with it marked, ↑ ↓ between them), copies the screen's text, and sizes the text (pinching the screen does too; each device keeps its own). The + at the top starts a new session in your home directory. A pane whose program ended (with remain-on-exit on) says how it ended, and Run it again starts the program again. A full-screen program (Codex or pi as they come, vim) keeps no history: a drag up or down on its screen scrolls it instead, as the wheel does on the computer, and the pane's bar says so.

The 📎 beside the box sends files from the phone into the pane's folder: keepane-uploads under the pane's directory (a name apart from a project's own uploads), or set -g web-upload-dir <folder> (relative: under the pane's directory; absolute: there, for every pane). A folder keepane makes holds a .gitignore of *, so git status stays as it was; one there already gets nothing. Pick one or more; each goes with its progress, then its full path shows with a button to copy it (nothing is typed into the pane). A name already there is not written over: the file becomes report (1).pdf. One file may be up to web-upload-max (default 2G); the status line says each one that came, and from where. A page started --read-only has no button, and a pane copied from another machine takes none (it would go to this one). Like the page, plain HTTP: on a network you do not trust, use the Tailscale address.

The same page works in a computer's browser: on a wide screen the list stays on the left and the pane fills the right. The button at the top left folds the list down to a strip of one button per pane (and back); on a touch screen a swipe left on the list folds it, a swipe right on the strip opens it. The switch at the top right turns the page light or dark: its glass knob slides across, and the specks of light in it gather into a sun or a moon. The menu beside it also has "like the system" (each device keeps its choice), and the terminal's theme (theme, see Themes): that one is the computer's, so its terminal changes too, and every page shows the panes in it. The same menu picks the page's language: the system's (Chinese on a Chinese system, else English), Chinese or English. Left of the switch, the time a request takes to the computer and back (23 ms, a green dot under 100 ms, yellow under 300, red above or offline). The full-screen button in a pane's bar leaves only its screen and the input box, over the whole screen where the browser can (on an iPhone, over the whole page); the button beside the box, or the browser's own way out, brings the rest back, and the list button beside it picks another pane without leaving full screen. (The page is built from web/, React and HeroUI, into one file keepane carries.)

keepane web on a phone: the list of panes with the program each runs, and one pane showing a coloured git log with each command's time in a column on the left, a row of keys and a box to type in

The code carries the address and a key made fresh at each start (128 random bits); nothing but the page itself answers without it, and the phone can only look, type into a pane and use that menu: no command of its own reaches keepane. It is off until started. Once started, the keepane server serves it in the background, so the terminal you ran keepane web in is free again, and it keeps serving until you stop it or the server exits:

keepane web status   # the address, and who is connected (watching which pane)
keepane web stop     # end it; the phones on it are cut off
keepane web          # while it runs: the same code again, to scan

When the sessions come back (keepane startup, keepane restart-server), it comes back with them, the way it was served, until keepane web stop. To have it on whenever keepane runs, put web-start -k in ~/.keepane.conf: the server starts it itself, with the same code each time (-k, below). Serving on this machine's addresses (no --bind), it looks at them again every 10 seconds: an address that came (Tailscale up after logon, another Wi-Fi) is served on too.

While it serves, the status line shows web and how many are connected (#{web_url} and #{web_clients}, for a status line of your own), the dashboard (prefix v) says the same over its pane list, and a phone connecting, or a request with a wrong key, is said on the status line.

keepane web --read-only     # look, but not type
keepane web --keep-key      # the same code next time, so a bookmark keeps working
keepane web --port 8080 --bind 192.168.1.23   # another port, or another network card
keepane web --bind 192.168.1.23,10.0.0.5     # more than one card: each address (or -b again); the code is for the first

It is plain HTTP, meant for your own network: on a shared one, someone watching the traffic could read the key. From elsewhere, put a private network such as Tailscale in between: keepane web listens on this machine's network address and on its Tailscale addresses (web status lists them). Windows asks once whether keepane may use the network; allow it for private networks.

Sharing a file or a folder

One command gives out a file or a folder by a link: scan its code with the phone, or open the link on another machine, and it downloads.

keepane share report.pdf            # a file: a code to scan and a link
keepane share ~/photos --for 2h     # a folder (as photos.zip), for 2 hours
keepane share build.log --once      # gone after one whole download
keepane share                       # what is shared (or -l; -l -J as JSON)
keepane share stop 2                # end one; --all ends every one
keepane share extend 2 --for 7d     # longer, on the same link
keepane share again 2               # the same thing on a new link

Each share has a link of its own (a random token, not the phone page's key): whoever has it can download that one thing and see nothing else. A share lasts 24 hours unless --for says (30m, 2h, 7d; 0 until it is stopped). A file downloads as it is, and a download cut off carries on where it stopped; a folder downloads as a zip written while it is read (links in it are left out). Whatever is shared is sent as a download, never shown as a page. The link is on the phone page's address and port: when that is off, share turns it on. The status line says each share, who downloads it and when it went, also when an agent in a pane shares something.

The list of shares is kept like the saved sessions (share/shares.json in the sessions directory). While no server runs no link works; the next server to start brings each share back on the same link (with the sessions, restore-on-start), the page served for them. The address may change with the network (a Tailscale address does not), and the link stays only on the same port: the status line says when it moved. A share whose time ran out meanwhile has ended. share extend brings an expired one back on its link; a stopped one, or one that went once, is shared again only on a new link (share again). The last 100 ended shares stay listed, each with how it ended and what happened to it. Page 3 of the dashboard (prefix v, then <) shows them all. Plain HTTP, like the page: across a network you do not trust, use Tailscale. The design: docs/design/share.md.

Told when a pane is done

keepane knows when a pane is done: a command that ran a while ended (its shell reports its commands, as for the command times), an agent finished its turn (its hook ran keepane pane-ready), an agent waits for you (it asks a permission or a question: its hook ran keepane pane-wait), a message's task ended, a program exited, or a pane with no agent in it rang the bell. It tells you where you are:

  • The phone's page, while it is open: a banner across the top (tap it to go to the pane), a short sound, a buzz on Android, and the count in the tab's title. What was done while the page was hidden is told when it is shown again. A page cannot raise a notification over plain HTTP, and a phone stops a page it is not showing, so for a locked phone use the hook or the webhook.
  • The desktop, with set -g notify on.
  • A webhook: set -g done-webhook <address> and keepane posts each one there, through curl, in the shape done-webhook-format names: json (keepane's own), text (the line alone: ntfy, Bark), feishu, wecom, dingtalk, slack or discord (a chat's incoming webhook). A chat's message starts with keepane, which a Feishu or DingTalk bot's keyword check can be set to; a chat that refuses shows in show-messages. A Feishu or DingTalk bot set to check signatures needs its secret in done-webhook-secret; keepane then signs each message as the bot expects.
  • The pane-done hook, for anything else. What it is about is in its environment: KEEPANE_DONE_KIND (command, agent, wait, task, exit, bell), KEEPANE_DONE_TEXT (the line), KEEPANE_DONE_OUTPUT (what the pane printed last, a line each), KEEPANE_DONE_PANE, KEEPANE_DONE_NAME, KEEPANE_DONE_OK (1 or 0, when known), KEEPANE_DONE_EXIT (the exit code, when the shell gave it: PowerShell says only whether a command failed), KEEPANE_DONE_SECONDS, KEEPANE_DONE_GIT (an agent's work in its repository, in a line; see below), and KEEPANE_DONE_JSON.
set -g done-webhook https://open.feishu.cn/open-apis/bot/v2/hook/<token>
set -g done-webhook-format feishu
set -g done-webhook-secret <secret>  # if the bot checks signatures
# ntfy (an app on iOS and Android), from the hook: sh on Linux and macOS
set-hook -g pane-done run-shell 'curl -s -d "$KEEPANE_DONE_TEXT" ntfy.sh/<your-topic>'
# ... and PowerShell on Windows
set-hook -g pane-done run-shell 'curl.exe -s -d $env:KEEPANE_DONE_TEXT ntfy.sh/<your-topic>'

What counts, and for which panes:

set -g done-events command agent wait  # any of command agent wait task exit bell; all; none
set -g done-after 30              # seconds a command must run to count
set -g done-panes named           # panes with a name or in ai/shell mode; all for every pane
set -g done-lines 5               # the last lines the pane printed go with it (0: none)

Each telling carries what the pane printed last (a command's own lines; an agent's last pane-status), under the line in a chat or a notification, and as output in keepane's JSON.

A pane is told of once in three seconds: an agent's turn and the task it finished are one telling. keepane list-done lists the last hundred.

wait comes from an agent's waiting hook (keepane setup, above), with what it says: waits for you: Claude needs your permission. The pane's last lines go with it (done-lines): for a permission, the question and its choices, the command among them. Any program can say it too: keepane pane-wait "deploy to production?". bell is off by default. It covers panes with no agent in them: an agent's bell means its turn ended or it has a question, and agent and wait tell that better. A pane's bell is told once a minute at most.

Answer the panes from Feishu

With a Feishu (Lark) app of your own, the tellings come from the app, and you answer them in the chat. keepane opens the app's long connection itself: nothing on this machine is reachable from outside, and no public address is needed.

  • Reply to a pane that waits for you (wait): your reply goes in at once. One key is pressed as it is: 1, 2, y, n, esc, enter, up, down, tab. Other text is typed, then Enter.
  • Reply to any other telling: your reply goes to that pane as a message, as send-message sends one. An agent's pane gets it when the agent is free; a normal pane keeps it for read-message. When the agent answers it (send-message -r), the answer comes back to the chat.
  • Commands: /panes (the panes, and which wait for you), /to <pane> <text> (a message), /key <pane> <keys> (keys now), /screen <pane> (what the pane shows) and /help.

Only the people you let in are heard, only in a chat with the bot alone. Messages go to agents' panes and normal ones, and keys to agents. Keys where no agent runs, and messages to shell panes, run commands: they need --shell. /screen sends what a pane shows to Feishu's servers: it needs --screen. Another machine's panes here (of a machine that gave this one --full, below) are left out of /panes and refused to /to, /key and /screen, unless the person is let in to them with --remote: that machine trusted you, not everyone you let in to the bot. Letting in works only outside the panes, so an agent cannot let anyone in. A reply to a question that is over presses nothing. Each telling carries the pane's last lines, as the webhook's do (done-lines; 0 sends none). Everything that came in, and what was done, is in the event log (list-events).

To set it up:

  1. On the Feishu open platform (open.feishu.cn, or open.larksuite.com for Lark), create an enterprise self-built app and turn on its bot.
  2. Give it two permissions: read the messages users send the bot in private chats, and send messages as the app.
  3. Put its App ID and App Secret in keepane.conf (below), and wait for keepane feishu to say connected.
  4. In the app's event settings, choose to receive events through the long connection, and save (Feishu saves it only while keepane is connected). Add the event im.message.receive_v1. Leave the Encrypt Key empty.
  5. Publish a version of the app.
  6. Send the bot a message. It answers with your open_id and the command that lets you in: run it in a terminal outside keepane.
set -g feishu-app-id cli_xxxxxxxx
set -g feishu-app-secret <secret>     # show-options prints (set)
set -g feishu-domain feishu           # lark for Lark
set -g feishu-notify on               # the tellings come from the app
keepane feishu                        # connected or not, and who is let in
keepane feishu allow ou_xxxx          # let an account in
keepane feishu allow ou_xxxx --shell --screen
keepane feishu allow ou_xxxx --remote # other machines' panes here too
keepane feishu remove ou_xxxx

Feishu gives each event to one connection of an app. Use one app per machine: two machines on one app get the messages at random. The design: docs/design/feishu.md.

What a pane's repository says

When a pane's directory is in a git repository, keepane reads it for two things: what is there now, and what an agent's work did.

What is there now shows after the branch in the status line and on the clock: main ●3 ↑2 ↓1 !1 is 3 files changed (new ones too), 2 commits ahead of the upstream, 1 behind, 1 file in conflict; nothing is shown for what there is none of. The variables are git_branch, git_head (the commit, short), git_changed, git_ahead, git_behind, git_conflicts (each empty at none) and git_marks (all of it as above), for a pane-border-format or a status line of your own. The dashboard shows the same on a line of the chosen pane.

What an agent's work did goes with its end, in an ai pane: measured from the commit the repository was at when the work began (its message was delivered, or someone typed to it while it was free), it is the commits made since, what in the working tree differs from that commit (each file's lines added and removed) and the new files git does not track yet:

git:
main 1a2b3c4..5d6e7f8: 1 commit, 2 files +40 -12, 1 new file
  5d6e7f8 parse the header
  src/parser.rs +38 -12
  src/lib.rs +2 -0
  new notes.md

It is under the message in trace-message (and git in its JSON), so a lead that waits with trace-message <id> -w gets it with the answer; and it goes with the telling (list-done, the webhook, the desktop notification, KEEPANE_DONE_GIT and git in KEEPANE_DONE_JSON). The message counts as done, and is told of, once this is read: git runs on a thread of its own, so nothing else waits (here, a tenth of a second with 3000 new files in the repository). A work that ends in another repository than it began in, or whose first commit was rebased away, is measured from where it ends and says (start unknown); when git is there but cannot answer, it says changes unknown (git failed). It is what changed in the working tree since the work began, whoever changed it: two agents in one working tree share it, so give each its own worktree (git worktree add) when that matters.

git is run only for what it alone can say, never while the server waits for it, each time for at most 10 seconds (an agent's work takes up to four), and never taking the index's lock from an agent at work in the same repository (--no-optional-locks). keepane runs it on its own, in whatever repository a pane is in, so it turns off the programs a repository's own config can name for it to start: the file watcher (core.fsmonitor), an external diff, text conversion and the pager. What git status of your own would still run there (a filter such as Git LFS's) it runs too. The status is asked again at most every 10 seconds while something shows it, and at once after a command or a turn ends there. keepane uses the git on the PATH, else where Git for Windows, GitHub Desktop or Homebrew put it; set -g git-command <path> names another. Without git, the branch and the commit ids are still read from the repository's own files, the figures are left empty, and an agent's work says changes unknown (git not found).

Across machines

Panes on two computers can message each other the same way panes on one do, over the port keepane web serves on, once the two keepane servers are paired. It works like SSH keys: each server has a key pair of its own and a table of the machines it lets in, and pairing puts each one's key in the other's table, once. On the machine to pair with, run keepane web and take the address it prints (the one the phone scans, key included); on this one:

keepane link add http://100.64.0.3:7681/#k=...     # pairs both ways, once
keepane link list                                  # the machines paired, and what each has of the other
keepane link panes 100.64.0.3:7681                 # its panes that this machine may reach
keepane send-message --to 100.64.0.3:7681/%worker "run the tests"

A pane there is written host:port/ and then the pane as that machine names it (%worker, $1:@3.%7). The message arrives with from= this machine and pane, so send-message -r there answers back here, into the same task. Both machines need keepane web running; the web key is used for the pairing only, and every request after it is signed with the server's own key, so a new web key changes nothing. A machine is known by its key, not its address: turning up from another network (Tailscale instead of the LAN), it is the same machine. The two clocks must agree to within two minutes.

Pairing gives nothing yet. One rule decides what a machine has: the machine being reached decides, so run these on the machine whose panes are to be seen. There are two levels:

keepane link share 100.64.0.3:7681 work          # a session: it sees it and may message its panes
keepane link share 100.64.0.3:7681 work:logs     # a window
keepane link share 100.64.0.3:7681 %worker       # a pane
keepane link unshare 100.64.0.3:7681 work        # no longer; --all for everything
keepane link allow 100.64.0.3:7681 --full        # all of this machine, as if it sat here
keepane link allow 100.64.0.3:7681 --none        # nothing, what was shared too

What is shared, the other machine sees (its chart in C-b w, link panes, link capture, link watch) and may send messages to; the rest of this machine does not exist for it. A session or window shared covers what comes to be in it later. A message goes by the pane's work mode, but a pane in shell mode takes none from a machine that only shares it: there a message runs as a command, which is control of this machine and takes --full. link share names such panes when it shares them. In the tree (C-b w), s shares what is under the cursor with the paired machine (a menu asks which when there are several), and s again takes it back; shared things read shared there. The marks are on the sessions, windows and panes themselves, so a name used again by something new is not shared; they go into the saves and come back with resume.

--full is all of it: every pane, typed into too (keepane link watch), every session, worked in from there (under this machine's name in its C-b w), its messages run in shell panes, and it may start panes and send commits and projects here. Plain HTTP can be read by anyone on the network, so --full is taken only over Tailscale (or from this machine); from a LAN address the machine has only what is shared, and is told why. --full --lan takes it from any network.

Sharing and --full are given from a terminal outside keepane or at the C-b : prompt, never from inside a pane, where an agent could let another machine in. An answer to a message a pane here sent comes back to that pane whether it is shared or not. In 0.56 and 0.57 a shared shell pane ran the messages of every machine it was shared with. Up to 0.55 there were five permissions (--shell, --screen, --panes, --push, --agents). Up to 0.76 a table of then was read (all five as --full); from 0.77 its words are not read: a machine paired before 0.56 and not given anything since has nothing until link allow --full or link share.

keepane link disconnect 100.64.0.3:7681        # stop asking it (this side only; it still has what it was given); link connect: again
keepane link remove 100.64.0.3:7681            # unpair, on both; what was shared goes too (link add pairs again)
keepane link trust 100.64.0.3:7681 <key>       # by hand, with the key `keepane link id` prints there (--full too)
keepane link rekey                             # a new key: every pairing has to be made again

What the other machine can be asked, beyond its panes:

keepane link info 100.64.0.3:7681              # its name, system, keepane, uptime, CPU, memory, the panes it shares
keepane trace-message 12 -w 60                 # a message sent there: what became of it there (and a command's output)
keepane link capture -S 100 100.64.0.3:7681/%worker   # what a pane there shows (shared with this machine)
keepane link watch 100.64.0.3:7681/%worker            # that pane, live, in this terminal
keepane link attach 100.64.0.3:7681 work              # that session, as if attached there (--full)
keepane link mirror 100.64.0.3:7681                   # follow its sessions again now (--stop: not until asked)
keepane show-mirror 100.64.0.3:7681                   # what is kept of it here (-t %3: a pane's screen)
keepane link list -J                                  # the paired machines as JSON, none of them asked

The sessions of a machine that gave this one --full are worked in from here. They are that machine's, and are shown under it and nowhere else: in the chart of C-b w (and C-b s) each paired machine is a block with its sessions below it; the tree and the list give each machine a heading; C-b v groups the panes by machine. list-sessions lists this machine's alone, and C-b ) ( go round the sessions of the machine the current one is of. Enter on one goes into it: it is looked at and typed into as any other, with this machine's keys, theme and copy mode; what is typed goes to the pane there (while the connection is down it is let go, and show-mirror counts it). Its status line reads work@100.64.0.3:7681; 100.64.0.3:7681/work names it in a command, 100.64.0.3:7681/%3 its pane 3, and #{pane_machine} is 100.64.0.3:7681 in it, #{pane_host} that machine's name. Its panes keep their names there (#{pane_name}, C-b v), but %name here is always this machine's pane.

A split, a kill, a resize, a zoom or a rename of it (by its keys, the mouse on a border, or a command) is done there, by that machine, and shows here when done. A kill by a key asks first and says where: kill-pane 1? (y/n) on DFINE (100.64.0.3:7681). A session killed from another machine keeps its save there, so that machine's next start brings it back; one killed there by hand stays away, as always. A split or a new window puts the eye here on the new pane, and leaves that machine's own terminals looking where they were (keepane 0.69 or later there). A zoom zooms the pane it is asked for, there too. The pane looked at here is chosen here: what that machine looks at, a zoom moved there included, changes it only when it is gone. A pane never moves between machines, and piping, recording or saving it from here is refused. Looking at it never resizes it there. A terminal smaller than the session shows part of it, panned as for any session too big for it. Each paired machine is followed by itself over an encrypted connection; one that has not given --full says no, and is asked again once a minute. That machine needs keepane 0.63 or later. Its sessions are not saved here, and a third machine does not see them through this one. (Up to 0.71 they were listed among this machine's own sessions, as copies.)

Each machine decides two things, and only for itself:

  • Connecting is whether this machine asks the other one. keepane link disconnect 100.64.0.3:7681 stops it: the other machine's sessions go from here, and nothing is asked of it or sent to it. It stays so across restarts; keepane link connect (from outside a pane) asks it again. This is this machine's side only: the other machine still connects here whenever it likes, and has what it was given here.
  • What it has here is what this machine gives the other one: link share / link unshare, link allow --full. keepane link allow 100.64.0.3:7681 --none takes all of it back: the other machine stays paired, but sees and reaches nothing here. keepane link remove unpairs, on both machines.

So to stop looking at a machine, disconnect it; to keep it out, take back what it has, or unpair. (Up to 0.79 a disconnect also refused what the other machine asked, so both had to connect again.) In the chart of C-b w, on a machine's block, the key line says what it has here (has full, has 2 shared, has nothing); c connects, x disconnects, R takes back what it has here and D forgets the pairing (R and D ask first); in C-b v, L lists the machines for the same.

A pane of another machine opens live here: Enter on it in the chart of C-b w opens a window watching it (Enter again goes to that window while it is open), and keepane link watch does the same in any terminal. The window is named after the pane's name there (else its window's, else its number) and the machine's: raqs@macbook; C-b v says it runs watch raqs@macbook (#{pane_watch}). The watch is an ordinary program in an ordinary pane, so zoom, splits, copy mode and C-b v treat it as any pane, and resume brings it back. It shows the pane at that pane's size, cut to fit and following its cursor (down to the pane's bottom when the cursor shows there). What is typed goes to that pane only when that machine gave this one --full: typing into a shell runs any command, so one pane is as much as all of them. A pane that is only shared is watched read-only, and q closes it.

A machine that gave this one --full can also be used as if you sat at it: keepane link attach 100.64.0.3:7681 [session] opens, in any terminal, a session attached there. That machine makes a client of this window's size, as keepane attach there would, and draws it; the status line, the prefix, the bindings, copy mode and C-b : are all that machine's, so C-b c opens a window there. Every key goes there, the prefix too: the window here is put in passthrough, and F12 gives the keys back to this machine (F12 again hands them over). C-b d there detaches and closes the window. When the network goes away, that machine lets the client go after 15 seconds; the window makes a new one when it comes back.

A machine that gave this one --full runs panes for it:

keepane link start 100.64.0.3:7681 -n helper -- claude   # its address there comes back
keepane send-message --to 100.64.0.3:7681/%helper "look at the failing test"
keepane link kill 100.64.0.3:7681/%helper               # only a pane this machine started there

The program must be one of that machine's agent-commands, with any arguments. A pane counts toward that machine's agent-pane-limit, for this machine alone. The pane goes in a session named after this machine (-s names another), with its work mode from its program as for a pane an agent makes (-m gives one). That machine keeps which panes this one started only while its server runs. Agents do the same through MCP: create_remote_pane, and kill_pane with the address.

A message for a pane not shared with the sender is answered as one for a pane that is not there, and the sender told how it could be shared, so a name says nothing of what is not shared. keepane web --read-only takes nothing from other machines either. When the other machine cannot be reached, the message fails at once (nothing is queued to be sent later); with -w, the other machine waits for it to be delivered, and one still queued when the time runs out is a time-out here, as it is for a pane on this machine. Pairing and unpairing are said on the status line and kept in the event log, and so are refused requests, once a minute for each address that sends them (a flood of bad requests fills neither). The design and every decision: docs/design/link.md.

Sending commits to another machine

A repository's commits go to a paired machine that gave this one --full, one way, committed work only. Run these in the repository:

keepane clone 100.64.0.3:7681                  # a copy there, in its link-clone-dir (~/keepane/<this repository's name>)
keepane clone 100.64.0.3:7681 ~/src/proj       # or at a path there (nothing there yet, or an empty directory)
keepane push                                   # later: the new commits of the current branch, to where it went
keepane push 100.64.0.3:7681 ~/src/proj        # to a repository already there (the same project), kept from now
keepane push --tell %worker                    # and a message to that pane there once they are in
keepane push -l                                # where this machine's repositories go

This machine keeps where each repository went, by the other machine's key, so a new address (another network) changes nothing; keepane push with no machine goes to the one it went to (name it when it went to more than one). Only the commits that machine lacks go, as a git bundle sent in pieces and checked whole before git takes it. There, the commits land in <this machine>/<branch>, and the branch moves on with them when that loses nothing: a fast-forward, its files too when it is checked out and no tracked file is changed. When that side has commits of its own on the branch, or changed files, the branch is left as it was and the answer says why, for that side to merge or rebase. A path names that machine's directories (~ its home). A repository already there is taken only when it shares a first commit with this one (or has no commit yet). A shallow clone is refused (its early history is not there to send: git fetch --unshallow first); Git LFS contents are not sent, only their pointer files. Files not committed here are counted in the answer and not sent. The status line there says what came, and the event log keeps it. link-push-limit (default 200M) bounds a bundle on both sides; both need git. Agents do it through MCP: push_repo. The design: docs/design/link-push.md.

Taking a project and its agents' chats to another machine

Claude Code, Codex and pi keep their chats on the machine they ran on. send-agents takes a project to a paired machine that gave this one --full, with the chats, so that you go on with them there:

keepane send-agents 100.64.0.3:7681 -n         # what would go (nothing is sent)
keepane send-agents 100.64.0.3:7681            # this project and its chats
keepane send-agents                            # later: what changed, to the same folder
keepane send-agents 100.64.0.3:7681 -s 9516c53b   # only the chats whose id starts so
keepane send-agents -l                         # what went where, and what came

Sent from a repository, its commits go as push sends them, with the files git lists as changed or new (ignored files stay); any other folder goes whole, without node_modules, target and the like. The chats go with their cwd set to the folder there. The first time, the project lands in ~/keepane/from/<this machine>/<name> there (under its link-clone-dir), and the answer ends with how to go on there:

go on there: cd /home/me/keepane/from/laptop/app
  claude --resume 9516c53b-ede9-4566-9d6a-76117964e69b

Both sides keep where the folder is. Sending again goes to the same folder and only what changed goes: a chat the other side has the start of goes as its new end. Sent back from there, the project goes back where it came from. Nothing of the other side's is lost: a file changed there since the last send stays, and the one sent lands beside it as <name>.from-<this machine>; a chat that went on there too (even opening it to resume adds to it) comes as a new chat, under a new id. It all goes as one gzip stream, in pieces, checked whole; link-agents-limit (default 1G) bounds it on both sides.

Chats can hold secrets: what the agent read, the commands it ran and their output. The link signs each request but does not encrypt it: use it over Tailscale, or on a network you trust. The design: docs/design/agent-sync.md.

The manual

keepane man prints the whole manual (every command, the default keys, the config, the environment and the files) as Markdown, the way docs/keepane.1.md is written: for reading, or to hand to a program. keepane man --roff writes it as a manual page; Homebrew installs that, so man keepane works. It lists every command, option, format variable, environment variable and MCP tool, and the tests keep it so. What of it keepane 1.x keeps, and what it does not (the group chat is experimental until a release says otherwise): docs/compatibility.md.

Configuration

~/.keepane.conf (or ~/.config/keepane/keepane.conf, or the file named by KEEPANE_CONFIG; ~ is %USERPROFILE% on Windows) holds one command per line, tmux syntax.

keepane reads only its own config, never ~/.tmux.conf. To bring a tmux config over, ask for it once:

keepane import-config -n     # show what would be written, write nothing
keepane import-config        # from ~/.tmux.conf (or ~/.config/tmux/tmux.conf)
keepane import-config some.conf -o ~/.keepane.conf   # any config, anywhere

Each line is tried the way keepane would read it at start. What it takes is written as it was (continuation lines and %if blocks keep their shape, every branch checked); the rest goes in commented out, with why: TPM and every @ plugin setting (tmux's plugins do not run in keepane), options tmux has and keepane has no use for (escape-time, mode-keys, ...), bindings of mouse "keys" such as MouseDragEnd1Pane (keepane's mouse handling is fixed), commands that run programs (run, if-shell: an import runs nothing), and anything keepane rejects. It goes into the config keepane reads (a new ~/.keepane.conf if there is none) and says so; a file imported once is refused the second time. A running server read its config when it started: keepane source-file ~/.keepane.conf applies the import now.

set -g prefix C-a
set -g default-shell wsl          # Windows: pwsh (default), powershell, wsl, cmd, or a path; elsewhere $SHELL (default) or a path
# set -g default-command "wsl.exe -d Ubuntu"
set -g mouse on
set -g history-limit 10000
set -g status-position top
set -g status-style fg=black,bg=colour39
set -g pane-active-border-style fg=colour39
set -g base-index 1               # windows and panes counted from 1
set -g pane-base-index 1

set -g repeat-time 500            # how long a `bind -r` key keeps working; 0 disables
set -g prefix-hint on             # a panel of what the keys do, when the key after the prefix is late
set -g prefix-hint-delay 500      # how late, in ms (0: at once)

set -g remain-on-exit on          # keep a pane whose program exited, showing why
set -g save-history 500           # lines of each pane saved for `resume`; 0 saves none, all saves the whole scrollback
set -g monitor-activity on        # flag a background window that prints (`#` on the status line)
set -g monitor-bell on            # and one that rings the bell (`!`); on by default
set -g monitor-silence 60         # flag one that has said nothing for 60s (`~`); 0 disables
set -g visual-bell on             # say it on the status line instead of ringing
set -g done-after 60              # tell of a command only when it ran a minute (see "Told when a pane is done")

set -g pane-timestamps on         # each command's time at the end of its line (prefix C-t flips it)
set -g log-history on             # keep what panes print, a file per pane per day (prefix / to read)
set -g log-history-days 30        # for how long; 0 keeps everything (log-history-dir moves the files)
set -g undo-kill-time 10          # seconds a killed pane or window can come back (prefix u); 0 for none
set -g keep-zoom off              # moving to another pane unzooms, as in tmux (on: the zoom moves with you)
set -g pane-border-lines single   # the lines between panes: heavy (the default), single, double or simple (ASCII)
set -g pane-frames on             # each pane in a rounded frame of its own, its pane-border-format text on top (off by default: the frame takes a column and a row on each side)
set -g animation off              # no frame flying to where the keys go (animation-time 160: its milliseconds, 0-10000)
set -g clock-mode-animation bars  # under the clock: pulse, matrix, bars, fire, starfield, sharks, bonsai, sea, cat, dino, penguins, synthwave, fireworks, random (the default), cycle or off
set -g clock-mode-look dots       # drawn in dots, blocks or binary; plain (the default) is its own characters
set -g clock-mode-zones "Asia/Shanghai,America/Los_Angeles"  # other places' time under the clock's date (IANA names, or a city alone: tokyo)
set -g dashboard-icons nerd       # the dashboard's [0] Files marks entries with a Nerd Font's icons (emoji by default)
set -g agent-cost off             # no price list fetched, no cost for the panes' agents (on by default)
set -g git-command C:\Tools\git\cmd\git.exe  # the git to run for the panes' repositories (default: the one found)
set -g web-upload-dir keepane-uploads  # where the phone page's 📎 puts files: under the pane's directory (absolute: there)
set -g web-upload-max 2G          # the largest file it takes (bytes, K, M or G)

bind -r h select-pane -L          # -r: press h h h after one prefix
bind -r j select-pane -D
bind -r k select-pane -U
bind -r l select-pane -R
bind | split-window -h
bind - split-window -v
bind -n M-Left previous-window     # -n: no prefix
bind -n M-Right next-window
bind r source-file ~/.keepane.conf

set -ag status-right " | keepane"    # -a adds to what the option already holds
source-file ~/.keepane/themes/nord.conf

Option names take an unambiguous abbreviation, the way command names do: set sync is set synchronize-panes, set mon-act on is set monitor-activity on, and each dash-separated word can be shortened (set w-s-f "#I:#W"). An on/off option with no value flips: set mouse, set sync. Something that could mean several options says which (set mon lists the three monitor-* ones).

Options unknown to keepane but common in .tmux.conf (escape-time, focus-events, ...) are accepted and ignored if they are set anyway (by a source-file of a tmux config, say); import-config leaves them out. default-terminal (xterm-256color unless set) is the TERM panes get on Linux and macOS; on Windows ConPTY sets up the terminal and the option does nothing.

Environment

set-environment NAME value adds a variable to the environment every pane gets, or changes it; set-environment -u NAME takes it out. A pane started afterwards has it from the start. A shell already open takes the change at its next prompt (PowerShell, bash, zsh, fish and a wsl.exe pane's shell, through keepane's prompt hook), so whatever it runs from then on has it. A program already running keeps the environment it started with: no program can change another's, so restart it (respawn-pane -k) to give it the new one. A variable the shell itself set since it started (or since the last change to that name) is not set over. The table is saved with the sessions and is there again after the server restarts; ~/.keepane.conf is read first, and wins for the names it sets.

-u takes a name out even when the server itself was started with it: a new pane starts from the server's own environment, which is whatever the shell that started the server had. A server started from an agent's shell, for example, has its NO_COLOR=1, and the programs in its panes that follow that convention draw without colour; set-environment -u NO_COLOR gives the colour back to the panes started after it. A name taken away stays away after a restart, too.

set-environment GOPROXY https://goproxy.cn    # in every pane, from its next prompt
set-environment -u GOPROXY                    # and gone again
set-environment -u NO_COLOR                   # gone, though the server was started with it

prefix e shows it in colour: the variables set-environment set, then what keepane sets in every pane itself (KEEPANE, the pane's own KEEPANE_PANE, PATH with keepane's folder in it, ...), and the names taken away. A script gets the plain NAME=value lines from keepane show-environment.

Themes

keepane looks like ink on paper out of the box (paper-dark): the panes in the colours of the code on dfine.tech at night (Vitesse Dark on a warm near-black), a quiet bar in soft ink, and one accent, cinnabar, for the session's block, the current window and the active pane's outline. themes/ in this repository holds other colour schemes (Nord, Gruvbox dark, Dracula, Catppuccin Mocha, Tokyo Night and Tokyo Day), Paper Dark itself to edit, and plain.conf, tmux's plain green bar. They are ordinary keepane commands, so a theme is just a file to source and an easy thing to copy and edit:

source-file ~/.keepane/themes/dracula.conf
source-file ~/.keepane/themes/plain.conf   # tmux's look instead

Four themes are built in, to switch with one option (or from the phone's page): paper-dark, the default, and paper, its light one (white paper, as the code on dfine.tech by day); tokyo-night, the default up to 0.37, and tokyo-day, its light one.

set -g theme paper

keepane draws in the terminal it runs in, so with tokyo-night a pane's background and the colours programs use (their red, blue...) are the terminal's own. The other three draw them themselves, so they look the same in any terminal: they set window-style (a pane's default text and background, as in tmux) and pane-colours (the 16 colours programs use, the first 16 of the palette). Their text colours (all but black, which programs draw on colour) read at 4.5:1 or more on the panes and the bar. A theme sets these and the status line and borders all at once, so set the theme first and your own changes after it. Once one of those options is set some other way (a theme file, by hand), the look is no built-in theme's and show -gv theme says custom. For the panes in the terminal's own colours under another theme: set -g window-style default and set -g pane-colours "".

The default look uses 24-bit colours. On a terminal without them (macOS's Terminal, unless it says COLORTERM=truecolor), keepane shows the nearest of the 256 colours instead, for its own look and for programs in panes.

Status line

status-left, status-right, window-status-format, window-status-current-format and pane-border-format take tmux format strings: #S session, #W window name, #I window index, #P pane index, #T pane title, #H host, #F flags, #{session_name}-style names, #{?flag,then,else} conditionals (#{?window_flags,busy,idle}, #{?session_name==work,…,…}), %H:%M time fields, #[fg=colour39,bg=black,bold] style changes and #(command), which runs the command every status-interval seconds (default 15) and shows its first line (a one-shot display-message -p or jobs -F runs it right away, giving up after 3 s). status-left-length / status-right-length clip. status-justify left|centre|right|absolute-centre places the window list, and window-status-separator is what goes between the labels (a space by default). With more windows than fit, the right side stays whole and the windows around the current one fill the rest, < and > marking where some are left out when there is a column for them (as in tmux), reversed when a window left out there has an alert; only a right side too long for the current window gives way, as far as that window and its marks need, cut at its start and marked … so the clock at its end stays.

The variables, by kind:

  • session: session_name session_id session_windows session_attached session_created
  • window: window_name window_id window_index window_panes window_active window_last_flag window_zoomed_flag window_width window_height window_bell_flag window_activity_flag window_silence_flag window_flags
  • pane: pane_index pane_id pane_title pane_current_command pane_start_command pane_current_path pane_width pane_height pane_active pane_dead pane_dead_status alternate_on mouse_any_flag pane_synchronized pane_in_mode pane_passthrough pane_pid pane_start_time pane_activity pane_dead_time pane_last pane_mode pane_top pane_left pane_bottom pane_right pane_at_top pane_at_bottom pane_at_left pane_at_right cursor_x cursor_y history_size history_limit
  • client: client_width client_height client_name client_session client_created client_activity client_prefix
  • server: host host_short socket_path version pid. Also session_activity session_last_attached window_activity window_start_flag window_end_flag window_layout.

The machine, read in-process with no #(command) needed: cpu_percentage ram_percentage ram_used battery_percentage (empty without a battery) battery_charging uptime. Other variables used often: git_branch (the branch of the pane's directory, read from .git, empty outside a repository; git_marks and the other git_* in What a pane's repository says), pane_current_path_short (~ for home), pane_pid_command (the program the pane is running right now, cargo during a build) and pane_output_count (how many times the pane has printed; a script can compare two readings to tell whether anything changed, which pane_activity, in whole seconds, cannot). keepane_update is a newer keepane's version once the daily check found one. The agent_* variables describe the agent a pane runs (What the agents use and cost).

The network: local_ip is the address this machine reaches the network from (read from the system, nothing sent), and public_ip the address the internet sees it at. Only a service outside knows the second, so keepane asks one (api.ipify.org, every ten minutes) only while a format that is drawn uses #{public_ip}; without it nobody is asked. Neither is in the default look; to show them:

set -ag status-right " #{local_ip} #{public_ip}"

The default status-right uses the machine's (see themes/paper-dark.conf, which is the default look written out, and themes/plain.conf for tmux's); set -g status-right ... replaces it, and set -g status off hides the line (prompts and messages then show over the bottom row).

Comparisons, as in tmux: #{==:a,b} #{!=:a,b} #{<:a,b} #{>:a,b} #{<=:a,b} #{>=:a,b} #{&&:a,b} #{||:a,b} and #{m:pattern,text} (a glob; m/i: ignores case) answer 1 or 0, and can be the condition of #{?…} or of a %if in the config file.

Modifiers, as in tmux: #{=10:pane_title} (first 10 characters), #{=-10:…} (last 10), #{b:pane_current_path} (basename), #{d:…} (dirname), #{t:session_created} (a time as a clock), #{s/foo/bar/:…} (substitution); they nest (#{=8:b:pane_current_path}).

set -g pane-border-status top (or bottom) puts a line of pane-border-format on every pane's border: by default the pane's number and title, the active pane's in bold.

set -g status-right "#[fg=yellow]#(pwsh -NoProfile -c (Get-Date).ToString('HH:mm'))#[default] #H"

Plugins

Plugins work the way tmux plugins do: a plugin is a directory with a <name>.keepane (or plugin.keepane) file of keepane commands, plus any scripts it needs, in any language. Scripts call back through the CLI: KEEPANE holds the socket name and KEEPANE_PANE the pane, so keepane -L $env:KEEPANE display-message ... from a script reaches the right server.

# ~/.keepane.conf
set -g plugin-path ~/.keepane/plugins       # default
set -g @plugin demo                       # ~/.keepane/plugins/demo/demo.keepane
set -g @plugin C:\src\my-plugin           # or a path (dir or file)

Inside a plugin file you have everything the config has, plus:

  • run-shell [-b] [-t target] command runs a command (through pwsh) with the keepane environment; its output is shown when it finishes (-b: ignore).
  • set-hook -g <hook> <command> runs a command when something happens: after-new-session, after-new-window, after-split-window, after-select-window, after-select-pane, after-kill-pane, client-attached, client-detached, pane-exited, pane-done (see "Told when a pane is done"). set-hook -gu <hook> removes it; show-hooks lists them.
  • set -g @anything value stores a user option; show-options -gqv @anything reads it back (from a script: keepane -L $env:KEEPANE show-options -gqv @anything).
  • #(command) pieces on the status line (above).
  • load-plugin name-or-path and list-plugins at runtime.

A minimal plugin that shows an agent's progress file on the status line and pops the full log with prefix A:

# ~/.keepane/plugins/agent-status/agent-status.keepane
set -g status-right "#[fg=cyan]#(pwsh -NoProfile -File ~/.keepane/plugins/agent-status/summary.ps1)#[default] %H:%M"
set -g status-interval 5
bind A run-shell "pwsh -NoProfile -Command Get-Content $env:TEMP\agent.log -Tail 30"

Commands a script or a binding reaches for, beyond the obvious ones (keepane list-commands prints them all, and any unambiguous prefix works):

  • pipe-pane [-o] [-I] [-O] [-t target] [command] copies everything a pane prints into a command's standard input (-O, the default); with no command it stops. keepane pipe-pane "$input | Add-Content build.log" keeps a build log without touching the build (PowerShell reads all of its input before it runs, so that file is written when the pipe stops; a cmd.exe /c findstr ... > file command writes as lines arrive). -I goes the other way: what the command prints is typed into the pane, and the pipe ends with the command's output (-IO does both).

  • wait-for [-L|-U|-S] channel blocks until another client signals the channel (or unlocks it), so two scripts can take turns: keepane wait-for ready waits, keepane wait-for -S ready releases it.

  • wait-output [-t pane] [-a] [-i] [-w time] text... blocks until the pane prints a line holding one of the texts, prints that line and exits 0: start a dev server, then run the tests once it listens, without polling capture-pane:

    keepane send-keys -t dev 'npm run dev' Enter
    keepane wait-output -t dev -w 2m 'Local:' 'error' && npm test

    Only what comes after the cursor counts (a command typed after the wait began counts too, since the pane shows it); -a takes what the pane already holds as well, and a full-screen program's screen counts as it is. -i ignores case, -w gives up after that long (90, 2m, 1h) and exits 1, as it does when the pane's program ends or the pane goes. An agent has it as the wait_output tool.

  • display-menu [-T title] name key command ... opens a menu over the window; an empty name is a separator. display-popup [-E] [-w W] [-h H] [-x X] [-y Y] [-d dir] [command] runs a program in a box over the window (-E closes it when the program exits, -C closes it from outside; -x/-y take a column or row, a percentage, C for centred or R/B for the right or bottom edge, and the box is centred without them).

  • choose-client lists the attached clients and detaches the one picked.

  • send-keys -X <copy-command> drives copy mode, with tmux's command names (search-backward, begin-selection, copy-selection, ...).

  • capture-pane -p [-e] [-J] [-S -N] prints a pane, with the colours if asked (-e), wrapped lines joined back into one (-J), N lines of scrollback above it (-S -N, -S - for all of it).

  • find-text pattern searches what every pane has printed and says where each hit is and how far back: ft:0.0 -8 REDIS-TIMEOUT-here. -C matches case, -t narrows to a session or window, -n caps the hits per pane, -H looks through every day of the history log too (each hit with its day and line). keepane's find-window searches only window names and titles.

  • record [-t target] out.cast writes everything a pane prints from now on as an asciinema v2 file (resizes included); record -t target with no path stops. Play it back with asciinema play, upload it, or embed it in a page.

  • notify [-T title] message raises a desktop notification (a Windows toast, in the Action Center under keepane's own name), and set -g notify on sends one for every alert, so a job that ends while the terminal is behind other windows still reaches you. An alert's toast has a "Go to pane" button: it opens a keepane:// link that runs focus-pane, which switches every attached client to that pane and brings its window forward (best effort: Windows Terminal does not always let a window be raised from outside). The first toast registers two entries under HKCU\Software\Classes (the AppUserModelID and the keepane: protocol), nothing machine-wide; when a toast cannot be shown a tray balloon is used instead.

  • focus-pane %N is that command on its own: every attached client goes to pane %N (the id list-panes and #{pane_id} show).

  • jobs is the task board: one line per pane on the whole server, with whether its program is still running or what it exited with, how long it has been up, how long since it last printed, its pid, command and directory. -t session narrows it; -F format prints what you want instead (#{pane_start_time}, #{pane_activity} and #{pane_dead_time} are the raw times). prefix B (choose-jobs) is the same board as a picker: Enter goes to that pane, x kills it, r restarts it, and the rows update in place while it is open.

    PANE       STATE    UP     IDLE   PID    COMMAND       DIR
    build:0.0  running  2h13m  4s     21608  cargo build   C:\src\keepane
    web:0.0    exit 1   2h13m  1h02m  28748  npm run dev   C:\src\site
    

Every window and pane command accepts -t target as in tmux: session, session:window, :window, session:window.pane, and the window part may be an index, a name, +, - or !. %N is a pane by its id (as list-panes shows it), which stays the same pane as others come and go; list-panes -F prints a format for each pane. The one exception is select-pane, whose -t takes the pane to move to (next, last or an index) rather than a window target, next to -L -R -U -D.

How it works

keepane is a client. The first invocation starts a detached server process (keepane __server) that owns every session; clients talk to it over a per-user named pipe on Windows (\\.\pipe\keepane-<user>-<socket>) and a Unix socket elsewhere (keepane-<uid>/<socket>, see Install); choose the socket with -L. Each pane is a pseudo terminal (a ConPTY on Windows) with a vt100 terminal model on the server side; the server composites the visible panes, borders and status line into a frame and sends only the cells that changed to the attached client, which writes them to the console with VT sequences. The server exits when its last session ends. On Windows it leaves the job it was started in when that job allows it: OpenSSH runs each session in a kill-on-close job, so a server started over SSH would otherwise end with the connection. On Linux and macOS it runs in a session of its own, which a terminal's or an SSH connection's hang-up does not reach.

Environment inside panes: KEEPANE (socket name) and KEEPANE_PANE (pane id). A keepane command run inside a pane talks to the server that owns it, the way $TMUX works for tmux, so keepane ls from a script or a plugin needs no -L. Server log: %LOCALAPPDATA%\keepane\server.log (KEEPANE_LOG=debug for more). Past 5 MB it becomes server.log.1 and a new one starts, so a server that runs for months keeps at most about 10 MB of log.

When a key does nothing (the prefix, say), run keepane show-keys in that same terminal and press it: each key prints what the console handed over and the key keepane reads it as, and q quits. Nothing printed means the program hosting the terminal kept the key for itself (VS Code, for one, binds Ctrl+B). Hosts that pass input on as bytes rather than key events (SSH, some remote tools) send Ctrl+B as the character 0x02 with no Ctrl flag; keepane reads control characters the way tmux does, so that is still C-b.

The pipe carries a DACL that admits only the creating user (and SYSTEM), the Windows equivalent of tmux's mode-0700 socket directory (which is what the Unix socket gets). Every pane runs in a kill-on-close job object on Windows, and is hung up with its whole session elsewhere, so kill-pane, kill-session and a server exit take the whole process tree down, and a slow client console never makes the server buffer frames without bound: it drops to a full redraw instead.

vendor/vt100 is vt100 0.16.2 with a one-function fix for a panic when a pane shrinks through a wide (CJK) character; see vendor/vt100/KEEPANE-PATCH.md. The server also logs and survives any panic in a command (server.log).

Development

cargo test              # unit + end-to-end tests (spawns cmd.exe panes on Windows, sh elsewhere)
cargo clippy --all-targets

The web page has browser tests of its own (web/tests, run with e2e): see web/README.md.

CI runs both on Windows, Linux and macOS. The platform's own code lives in src/platform/windows and src/platform/unix, each with the same modules (see docs/design/platform.md). On Windows the tests/console.rs suite runs the real keepane.exe inside a ConPTY, so the console code path (raw input mode, alternate screen, detach cleanup) is covered without a human at the keyboard.

Not (yet) implemented

On Linux and macOS, keepane update (it says where the new version is) and desktop notifications with a "Go to pane" button are not there yet.

Compared with tmux, these differ for now:

  • Clients attached to the same session share one window size. window-size latest|smallest|largest|manual takes the size of the client used last, the smallest or the largest, or only what resize-window sets. A smaller client shows its own view of the window, panned with Shift+arrows (refresh-client -U/-D/-L/-R); the view follows the cursor while you type.
  • Hooks are only the events listed above; choose-tree filters by a substring, not by a tmux format.
  • In display-popup, the prefix key still belongs to keepane; pressing it twice sends it to the program in the box.

Pane messages: shell work mode needs keepane's prompt hook (PowerShell, bash, zsh, fish, and those in a wsl.exe pane), so cmd and sh do not take messages on their own yet (they can read-message); a pane started before keepane 0.15 has the older hook and must be restarted for it. The phone page shows each pane's inbox; the dashboard's tasks and events are not on it yet.

docs/tmux-parity.md has the command-by-command and key-by-key list.

Formerly wmux

Up to 0.13.1 the project was called wmux. Projects of that name already exist on GitHub, winget and crates.io, so from 0.14.0 it is keepane, from keep + pane: the programs in the panes keep running when the terminal is gone.

Coming from wmux: up to 0.76, keepane read wmux's names and keepane migrate moved a wmux setup over in one go; from 0.77 neither is there. Either install keepane 0.76 once and run keepane migrate (it moves the sessions of a wmux server still running, what wmux kept in %LOCALAPPDATA%\wmux, the start at logon, the Windows Terminal profile and the notification link), or rename by hand: ~/.wmux.conf to ~/.keepane.conf, WMUX_* to KEEPANE_*, ~/.wmux/plugins to ~/.keepane/plugins, *.wmux plugin files to *.keepane, and %LOCALAPPDATA%\wmux to %LOCALAPPDATA%\keepane while no server runs.

  • The MSI replaces the wmux one in "Apps & features". wmux update no longer finds anything: install keepane from the releases page once. With scoop, scoop uninstall wmux and install the keepane manifest (see Install).
  • The repository is now github.com/newdee/keepane (the old links lead there) and the site dfine.tech/keepane.
  • A tmux or wmux alias in your $PROFILE needs to point at keepane.

About

Pane as an actor | Persistent terminal panes, each with its own inbox: a terminal multiplexer.

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages