From 9843a1b32747c6578cce1b3a64500d4710713ec5 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Tue, 5 May 2026 22:59:59 +0200 Subject: [PATCH] README: document ControlMaster negotiation behaviour --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4644bb5..0d0cb2e 100644 --- a/README.md +++ b/README.md @@ -85,11 +85,14 @@ pi -e ~/src/src_local/pi-extensions/extensions/ssh-controlmaster.ts --ssh user@h **How it works:** -1. On `session_start`, establishes a ControlMaster: `ssh -fN -o ControlMaster=yes -o ControlPersist=yes -o ControlPath= ` -2. All tool calls use `-o ControlMaster=no -o ControlPath=` to multiplex over that socket — near-zero per-call overhead -3. The system prompt is patched to tell the LLM it's operating on ` (via SSH ControlMaster: )` -4. User `!` shell commands are also routed over SSH -5. On `session_shutdown`, sends `ssh -O exit` to cleanly tear down the master +1. On `session_start`, runs `ssh -G ` to read the effective config for that host +2. If `~/.ssh/config` already configures `ControlMaster auto` or `yes` for the host, the existing system socket is reused — no second connection is opened and pi does **not** tear down the master on exit (it was the system's to manage) +3. Otherwise pi establishes its own master: `ssh -fN -o ControlMaster=yes -o ControlPersist=yes -o ControlPath=/tmp/pi-cm-.sock ` and shuts it down cleanly on exit +4. All tool calls multiplex over the socket with `-o ControlMaster=no -o ControlPath=` — near-zero per-call overhead +5. The system prompt is patched to tell the LLM it's operating on ` (via SSH ControlMaster: )` +6. User `!` shell commands are also routed over SSH + +The status bar shows `⚡ own master` or `⚡ system master` so you can see which path was taken. **Status bar:** Shows `SSH ⚡ user@host:/path` when the master is ready, `⟳ connecting…` during setup, and an error state if the master fails to start.