tmux-ide 2.7.0 → 2.9.0-beta.5

package/skill/SKILL.md

@@ -7,7 +7,7 @@ session — a fleet of tabs with live agent-status glyphs, ground-truth
 working/blocked/done detection, notifications when an agent needs a human, and a
 crash-proof restore. It's built _around_ tmux (adopt is additive tmux config, no
 wrapper process), and the whole UI is one keystroke away — one interaction
-grammar, one theme file. `ide.yml` is optional; adopt works on any session.
+grammar, one theme file. `.tmux-ide/workspace.yml` is optional; adopt works on any session.
 
 ## When to use
 
@@ -16,7 +16,7 @@ grammar, one theme file. `ide.yml` is optional; adopt works on any session.
 - **You are an agent and want to report your own status** so the dock/fleet reflects it (the agent contract, below)
 - Post-crash recovery — a tmux server died and the user wants their fleet + Claude conversations back
 - User wants a git worktree (plus an adopted session) per branch
-- User wants to set up a multi-pane dev workspace with `ide.yml`
+- User wants to set up a multi-pane dev workspace with `.tmux-ide/workspace.yml`
 
 ## The agent contract
 
@@ -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
@@ -120,7 +206,7 @@ Right-click any pane or the bar opens the actions menu at the pointer.
 | Panels — explorer / changes / config       | `prefix e` `g` `v`    | `⌥e` `⌥g` `⌥,` |
 
 One interaction grammar everywhere: `j`/`k` move, `enter` opens, `/` filters,
-`esc` backs out, `?` asks. Bare `tmux-ide` with no `ide.yml` opens the **home
+`esc` backs out, `?` asks. Bare `tmux-ide` with no project config opens the **home
 cockpit** (the fleet home screen). `tmux-ide cheatsheet` prints the full sheet.
 
 ## The app — `tmux-ide app` (the terminal IDE)
@@ -145,10 +231,10 @@ screen) or `tmux-ide app <session>`. Needs `bun`, or a downloaded binary:
 - State persists across launches (~/.tmux-ide/app-state.json): last tab,
   session, open file.
 
-## ide.yml (optional)
+## .tmux-ide/workspace.yml (optional)
 
 Adopt works on any session. If you'd rather have tmux-ide build the layout, describe
-it in `ide.yml` (sessions launched from a config are adopted automatically).
+it in `.tmux-ide/workspace.yml` (sessions launched from a config are adopted automatically).
 
 **Setup workflow for a user's project:**
 
@@ -200,37 +286,36 @@ it in `ide.yml` (sessions launched from a config are adopted automatically).
 **Schema:**
 
 ```yaml
+version: 1
 name: my-app # tmux session name
-sidebar: true # inject the nav column at launch (prefix b / ⌥b); or { width: "30" }
 before: pnpm install # optional pre-launch shell hook
-theme: # optional per-session pane colors
-  accent: colour75
-  border: colour238
-rows:
-  - size: 70% # row height percent (rows split evenly if omitted)
-    panes:
-      - title: Claude # pane border label
-        command: claude # command to run (optional)
-        size: 50% # pane width percent (optional)
-        dir: apps/web # per-pane working directory (optional)
-        focus: true # initial focus (optional)
-        env: # environment variables (optional)
-          PORT: "3000"
-  - panes:
-      - title: Explorer
-        type: explorer # widget pane: explorer | changes | preview | config
-        target: src/ # optional widget target path
-      - title: Shell
+terminal:
+  theme: # optional per-session pane colors
+    accent: colour75
+    border: colour238
+  rows:
+    - size: 70% # row height percent (rows split evenly if omitted)
+      panes:
+        - title: Claude # pane border label
+          command: claude # command to run (optional)
+          size: 50% # pane width percent (optional)
+          dir: apps/web # per-pane working directory (optional)
+          focus: true # initial focus (optional)
+          env: # environment variables (optional)
+            PORT: "3000"
+    - panes:
+        - title: Explorer
+          type: explorer # widget pane: explorer | changes | preview | config
+          target: src/ # optional widget target path
+        - title: Shell
 ```
 
 Read config with `tmux-ide config --json`; mutate with `config set <dot.path> <value>`,
 `add-pane`, `remove-pane`, `add-row`; apply changes to a running session with
 `tmux-ide restart`.
 
-An optional mission/goal/task orchestrator exists as a **secondary** surface,
-configured via the `team` and `orchestrator` blocks in `ide.yml` (enable teams
-with `tmux-ide config enable-team --name <n>`). It's not the headline — see the
-Task System docs if a user explicitly wants coordinated multi-agent dispatch.
+Mission runtime wiring is future work for the workspace config model. Do not add
+mission or orchestrator runtime fields to `.tmux-ide/workspace.yml` yet.
 
 ## Config — ~/.tmux-ide/config.json
 

package/templates/agent-team-monorepo.yml

@@ -1,39 +1,37 @@
 name: my-monorepo
+version: 1
 
 # Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
 # comes from Claude Code's lifecycle hooks. Wire them once with:
 #   tmux-ide integration install claude
 
-team:
-  name: my-monorepo
-
-sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
-
 before: pnpm install
 
-rows:
-  - size: 70%
-    panes:
-      - title: Lead — Architect
-        command: claude
-        role: lead
-        focus: true
-      - title: Frontend Agent
-        command: claude
-        role: teammate
-        task: "Work on the frontend application"
-        dir: apps/web
-      - title: Backend Agent
-        command: claude
-        role: teammate
-        task: "Work on the backend services"
-        dir: apps/api
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-lead
+          title: Lead — Architect
+          command: claude
+          focus: true
+        - id: agent-frontend
+          title: Frontend Agent
+          command: claude
+          dir: apps/web
+        - id: agent-backend
+          title: Backend Agent
+          command: claude
+          dir: apps/api
 
-  - panes:
-      - title: Frontend
-        command: pnpm dev
-        dir: apps/web
-      - title: Backend
-        command: pnpm dev
-        dir: apps/api
-      - title: Shell
+    - panes:
+        - id: dev-frontend
+          title: Frontend
+          command: pnpm dev
+          dir: apps/web
+        - id: dev-backend
+          title: Backend
+          command: pnpm dev
+          dir: apps/api
+        - id: shell
+          title: Shell

package/templates/agent-team-nextjs.yml

@@ -1,35 +1,33 @@
 name: my-app
+version: 1
 
 # Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
 # comes from Claude Code's lifecycle hooks. Wire them once with:
 #   tmux-ide integration install claude
 
-team:
-  name: my-app
-
-sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
-
 before: pnpm install
 
-rows:
-  - size: 70%
-    panes:
-      - title: Lead
-        command: claude
-        role: lead
-        focus: true
-      - title: Frontend
-        command: claude
-        role: teammate
-        task: "Work on React components and pages"
-      - title: Backend
-        command: claude
-        role: teammate
-        task: "Work on API routes and server logic"
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-lead
+          title: Lead
+          command: claude
+          focus: true
+        - id: agent-frontend
+          title: Frontend
+          command: claude
+        - id: agent-backend
+          title: Backend
+          command: claude
 
-  - panes:
-      - title: Next.js
-        command: pnpm dev
-      - title: Changes
-        type: changes # live git changes widget
-      - title: Shell
+    - panes:
+        - id: dev
+          title: Next.js
+          command: pnpm dev
+        - id: changes
+          title: Changes
+          type: changes # live git changes widget
+        - id: shell
+          title: Shell

package/templates/agent-team.yml

@@ -1,33 +1,33 @@
 name: my-project
+version: 1
 
 # Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
 # comes from Claude Code's lifecycle hooks. Wire them once with:
 #   tmux-ide integration install claude
 
-team:
-  name: my-project
-
-sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
-
 # before: npm install
 
-rows:
-  - size: 70%
-    panes:
-      - title: Lead
-        command: claude
-        role: lead
-        focus: true
-      - title: Teammate 1
-        command: claude
-        role: teammate
-      - title: Teammate 2
-        command: claude
-        role: teammate
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-lead
+          title: Lead
+          command: claude
+          focus: true
+        - id: agent-1
+          title: Teammate 1
+          command: claude
+        - id: agent-2
+          title: Teammate 2
+          command: claude
 
-  - panes:
-      - title: Changes
-        type: changes # live git changes widget
-      - title: Dev Server
-        # command: npm run dev
-      - title: Shell
+    - panes:
+        - id: changes
+          title: Changes
+          type: changes # live git changes widget
+        - id: dev
+          title: Dev Server
+          # command: npm run dev
+        - id: shell
+          title: Shell

package/templates/convex.yml

@@ -1,21 +1,29 @@
 name: my-app
+version: 1
 
 before: pnpm install
 
-rows:
-  - size: 70%
-    panes:
-      - title: Claude 1 — feature
-        command: claude
-      - title: Claude 2 — review
-        command: claude
-      - title: Claude 3 — explore
-        command: claude
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-1
+          title: Claude 1 — feature
+          command: claude
+        - id: agent-2
+          title: Claude 2 — review
+          command: claude
+        - id: agent-3
+          title: Claude 3 — explore
+          command: claude
 
-  - panes:
-      - title: Next.js
-        command: pnpm dev
-      - title: Convex
-        command: npx convex dev
-      - title: Shell
-        focus: true
+    - panes:
+        - id: dev
+          title: Next.js
+          command: pnpm dev
+        - id: convex
+          title: Convex
+          command: npx convex dev
+        - id: shell
+          title: Shell
+          focus: true

package/templates/default.yml

@@ -1,26 +1,31 @@
 name: my-project
+version: 1
 
 # before: npm install   # optional pre-launch hook (runs once, before panes start)
 
-# sidebar: true         # inject the fleet nav column (prefix b toggles it live)
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-1
+          title: Claude 1
+          command: claude
+        - id: agent-2
+          title: Claude 2
+          command: claude
 
-rows:
-  - size: 70%
-    panes:
-      - title: Claude 1
-        command: claude
-      - title: Claude 2
-        command: claude
-
-  - panes:
-      # Widget panes render native UI instead of a command:
-      #   type: explorer | changes | preview | config | sidebar
-      - title: Changes
-        type: changes # live git changes — no command, tmux-ide draws it
-      - title: Dev Server
-        # command: npm run dev
-        # dir: apps/web          # per-pane working directory
-        # env:                   # per-pane environment variables
-        #   PORT: "3000"
-      - title: Shell
-        focus: true # give this pane initial focus
+    - panes:
+        # Widget panes render native UI instead of a command:
+        #   type: explorer | changes | preview | config
+        - id: changes
+          title: Changes
+          type: changes # live git changes — no command, tmux-ide draws it
+        - id: dev
+          title: Dev Server
+          # command: npm run dev
+          # dir: apps/web          # per-pane working directory
+          # env:                   # per-pane environment variables
+          #   PORT: "3000"
+        - id: shell
+          title: Shell
+          focus: true # give this pane initial focus

package/templates/go.yml

@@ -1,19 +1,26 @@
 name: my-app
+version: 1
 
 before: go mod download
 
-rows:
-  - size: 70%
-    panes:
-      - title: Claude 1 — feature
-        command: claude
-      - title: Claude 2 — review
-        command: claude
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-1
+          title: Claude 1 — feature
+          command: claude
+        - id: agent-2
+          title: Claude 2 — review
+          command: claude
 
-  - panes:
-      - title: Go
-        command: go run .
-      - title: Changes
-        type: changes # live git changes widget
-      - title: Shell
-        focus: true
+    - panes:
+        - id: dev
+          title: Go
+          command: go run .
+        - id: changes
+          title: Changes
+          type: changes # live git changes widget
+        - id: shell
+          title: Shell
+          focus: true

package/templates/missions.yml

@@ -1,47 +1,32 @@
 name: project-name
+version: 1
 
 # Ground-truth agent status (working/blocked/done glyphs on the fleet tabs)
 # comes from Claude Code's lifecycle hooks. Wire them once with:
 #   tmux-ide integration install claude
 
-team:
-  name: missions
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-lead
+          title: Lead
+          command: claude
+          focus: true
+        - id: agent-frontend
+          title: Frontend
+          command: claude
+        - id: agent-backend
+          title: Backend
+          command: claude
 
-sidebar: true # fleet nav column — jump between agents (toggle: prefix b)
-
-rows:
-  - size: 70%
-    panes:
-      - title: Lead
-        command: claude
-        role: lead
-        focus: true
-      - title: Frontend
-        command: claude
-        role: teammate
-        specialty: frontend
-      - title: Backend
-        command: claude
-        role: teammate
-        specialty: backend
-
-  - size: 30%
-    panes:
-      - title: Validator
-        command: claude
-        role: validator
-        skill: reviewer
-      - title: Researcher
-        command: claude
-        role: researcher
-        specialty: researcher
-        skill: researcher
-      - title: Shell
-
-orchestrator:
-  enabled: true
-  auto_dispatch: true
-  dispatch_mode: missions
-  poll_interval: 5000
-  stall_timeout: 300000
-  master_pane: Lead
+    - size: 30%
+      panes:
+        - id: agent-validator
+          title: Validator
+          command: claude
+        - id: agent-researcher
+          title: Researcher
+          command: claude
+        - id: shell
+          title: Shell

package/templates/nextjs.yml

@@ -1,21 +1,29 @@
 name: my-app
+version: 1
 
 before: pnpm install
 
-rows:
-  - size: 70%
-    panes:
-      - title: Claude 1 — feature
-        command: claude
-      - title: Claude 2 — review
-        command: claude
-      - title: Claude 3 — explore
-        command: claude
+terminal:
+  rows:
+    - size: 70%
+      panes:
+        - id: agent-1
+          title: Claude 1 — feature
+          command: claude
+        - id: agent-2
+          title: Claude 2 — review
+          command: claude
+        - id: agent-3
+          title: Claude 3 — explore
+          command: claude
 
-  - panes:
-      - title: Next.js
-        command: pnpm dev
-      - title: Changes
-        type: changes # live git changes widget
-      - title: Shell
-        focus: true
+    - panes:
+        - id: dev
+          title: Next.js
+          command: pnpm dev
+        - id: changes
+          title: Changes
+          type: changes # live git changes widget
+        - id: shell
+          title: Shell
+          focus: true