tmux-ide 2.7.0 → 2.8.0

package/skill/SKILL.md

@@ -34,10 +34,26 @@ minutes is treated as stale (the detector falls back to Layer 2), so long-runnin
 agents should re-stamp periodically. Two optional companions:
 
 ```bash
-tmux set-option -p @agent_session_id "<id>"   # your Claude session id — powers restore --resume-agents
+tmux set-option -p @agent_session_id "<id>"   # your own session id — powers restore --resume-agents
 tmux set-option -p @agent_hint claude          # force which agent manifest Layer 2 uses for this pane
 ```
 
+**Display metadata** — say WHAT you're doing and WHO you are, right in the
+fleet UI. Two more optional pane-local options:
+
+```bash
+tmux set-option -p @agent_status_text "refactoring auth"  # one-liner, ≤32 chars — shows in the pane chip ("● claude · refactoring auth")
+tmux set-option -p @agent_display_name "reviewer"          # your name — replaces the detected kind in sidebar rows & chips
+```
+
+Plain text only (control characters are stripped, tabs break the line for your
+pane — don't stamp them; anything past 32 chars is ellipsized). Both surface in
+`tmux-ide team --json` (per-pane `statusText` / `displayName`), the unified
+app's pane chips, and the sidebar agent rows. They follow the SAME staleness
+rules as `@agent_state`: they only show while your state stamp is fresh, so
+re-stamp `@agent_state` alongside — update the text whenever your focus
+changes, and it disappears with a stale/cleared state instead of lying.
+
 **Claude Code users get this for free** — `tmux-ide integration install claude`
 writes a POSIX hook into `~/.claude/settings.json` that stamps `@agent_state` on
 every lifecycle event (UserPromptSubmit/PreToolUse → working, Notification →
@@ -45,6 +61,13 @@ blocked, Stop → done, SessionEnd → idle) and records `@agent_session_id`. It
 takes effect for **new** Claude Code sessions; the merge is reversible
 (`integration uninstall claude`).
 
+**Session-id capture for other kinds** (what `restore --resume-agents` resumes
+from): codex and cursor-agent panes are stamped **automatically** — the chrome
+updater reads each CLI's own on-disk session state; opencode gets a plugin via
+`tmux-ide integration install opencode`. `tmux-ide integration status` shows
+what's active. Kinds without a verified resume story (gemini, aider, copilot, …)
+can self-report the id as above.
+
 **How detection layers work:** Layer 1 is the authority above — a fresh
 `@agent_state` option is ground truth. When none is present, Layer 2 resolves the
 agent from the pane's process tree and reads the visible screen against
@@ -91,7 +114,7 @@ tmux-ide adopt --all                       # adopt every live session
 tmux-ide unadopt <session>                 # remove the dock — sessions keep running as plain tmux
 
 tmux-ide restore --dry-run --json          # preview rebuilding the fleet from the last snapshot
-tmux-ide restore --resume-agents           # rebuild after a tmux crash; revive Claude convos via claude --resume
+tmux-ide restore --resume-agents           # rebuild after a tmux crash; revive agent convos (claude/codex/cursor/opencode)
 
 tmux-ide worktree create <branch> --from <ref>   # git worktree on a new branch + a session in it
 tmux-ide worktree open <branch>            # open/switch to an existing worktree's session
@@ -102,6 +125,69 @@ tmux-ide update --dry-run                  # detect install method (dev checkout
 tmux-ide doctor                            # system + integration health (tmux version, TUI surfaces, skill freshness)
 ```
 
+## Drive tmux-ide over the socket (agent loops)
+
+The CLI above spawns a process per call. If you are driving the fleet in a
+loop — polling status, waiting on agents, reacting to transitions — start the
+control server once and keep ONE connection open instead:
+
+```bash
+tmux-ide serve &   # local Unix socket at ~/.tmux-ide/control.sock (0600, this user only)
+```
+
+**Frame format:** newline-delimited JSON, one object per line. Send
+`{"v":1,"id":<any>,"verb":"<verb>","params":{…}}`; you get back
+`{"v":1,"id":<same>,"ok":true,"data":…}` or
+`{"v":1,"id":<same>,"ok":false,"error":{"code","message"}}`. Responses
+correlate by `id` (they may arrive out of order — a long `wait` doesn't block
+other verbs on the same connection). After the `subscribe` verb the server
+also PUSHES unsolicited `{"v":1,"event":"agent-status","data":{ts,session,from,to}}`
+frames the moment its detection tick sees a session change state — no polling.
+
+**Verbs:** `fleet` (the `team --json` payload) · `agents` (per-pane entries,
+optional `{session}`) · `send` (`{session,target,message,noEnter?,dir?}`) ·
+`wait` (`{kind:"agent-status",session,status,timeoutMs?}` or
+`{kind:"output",target,match,timeoutMs?}`; a timeout is an error response with
+code `timeout`) · `spawn` (`{kind|command, session?|sessionName, dir?,
+placement?, paneId?}` → the new `paneId`) · `restart-agent` / `stop-agent`
+(`{paneId, kind|command}`) · `explain` (`{target}`) · `subscribe`.
+
+One-shot from a shell (nc keeps the pipe open for the response):
+
+```bash
+printf '{"v":1,"id":1,"verb":"fleet"}\n' | nc -U ~/.tmux-ide/control.sock | head -1
+```
+
+A subscribe loop from node:
+
+```js
+const net = require("node:net");
+const os = require("node:os");
+const sock = net.connect(`${os.homedir()}/.tmux-ide/control.sock`);
+let buf = "";
+sock.on("data", (chunk) => {
+  buf += chunk;
+  const lines = buf.split("\n");
+  buf = lines.pop();
+  for (const line of lines.filter(Boolean)) {
+    const frame = JSON.parse(line);
+    if (frame.event === "agent-status") console.log(frame.data); // react here
+  }
+});
+sock.write('{"v":1,"id":1,"verb":"subscribe"}\n');
+```
+
+Right after `subscribe`, the first tick reports every session once with
+`from:null` (a snapshot of where the fleet stands); real transitions follow.
+
+**Socket vs CLI:** prefer the socket for anything event-driven or repeated
+(subscribe replaces an `events --follow` poll; a server-held `wait` costs no
+spawn-per-poll). Prefer the CLI for one-shot reads and anything a human might
+re-run — it needs no server. With a server running, `tmux-ide events --follow
+--socket` and `tmux-ide wait … --socket` use it automatically and fall back to
+polling silently when it's gone. The server is local-only by design: no
+network listener, no tokens — filesystem permissions are the auth.
+
 ## Keys & surfaces to tell USERS about
 
 Once a session is adopted, the whole UI is a keystroke away. **Lead with the