joakimp/pi-extensions
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README: document ControlMaster negotiation behaviour

Browse Source
This commit is contained in:
Joakim Persson
2026-05-05 22:59:59 +02:00
parent 5aa8036a6f
commit 9843a1b327
1 changed files with 8 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+8 -5
View File
@@ -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=<socket> <remote>`
2. All tool calls use `-o ControlMaster=no -o ControlPath=<socket>` to multiplex over that socket — near-zero per-call overhead
3. The system prompt is patched to tell the LLM it's operating on `<remoteCwd> (via SSH ControlMaster: <remote>)`
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 <host>` 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-<pid>.sock <remote>` and shuts it down cleanly on exit
4. All tool calls multiplex over the socket with `-o ControlMaster=no -o ControlPath=<socket>` — near-zero per-call overhead
5. The system prompt is patched to tell the LLM it's operating on `<remoteCwd> (via SSH ControlMaster: <remote>)`
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.