Show live orchestrator output in Codex UI

.agents/skills/start-agent-team/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: start-agent-team
+description: Start and coordinate project-focused multiagent swarm teams using this repository's tmux orchestrator, and show read-only live orchestrator output in the Codex desktop UI. Use only when the user explicitly asks for an agent team, swarm team, worker team, orchestrator, or multiagent session for a coding project or repository.
+---
+
+# Start Agent Team
+
+## Launch
+
+Use this repository's `launch.sh` to start a tmux session with one orchestrator
+window. The orchestrator creates workers and long-running subagents for the
+target project.
+
+This skill is only for tmux-backed multiagent teams. Standalone agent or
+subagent requests should use native Codex UI agents instead.
+
+Default to a clean, non-attached launch:
+
+```bash
+REPO_ROOT/launch.sh --session SESSION --root PROJECT_ROOT --no-attach
+```
+
+- Use `multiagent-<repo-name>` unless the user supplies a session name.
+- Use the user's named project root, or the current git root for "this project."
+- Add `--resume` only for explicit recovery.
+- Keep `ORCHESTRATOR_CLI=codex` unless the user requests another backend.
+- Do not overwrite an existing tmux session.
+
+If the user supplied a task, inspect the orchestrator pane before sending it:
+
+```bash
+tmux capture-pane -t "SESSION:orchestrator" -p -S -200
+tmux send-keys -t "SESSION:orchestrator" "TOP_LEVEL_TASK" Enter
+```
+
+Do not send input while the orchestrator is starting, blocked on authentication,
+or busy. Keep the task high level and let the orchestrator decompose it.
+
+## Live Codex UI view
+
+After launch and task delivery, prefer a live read-only terminal view when the
+Codex desktop terminal-opening tool is available:
+
+1. Start the follower in PTY mode (`tty: true`) with a short yield. Keep the
+   returned running terminal `session_id`.
+
+   ```bash
+   REPO_ROOT/.agents/skills/start-agent-team/scripts/follow_orchestrator.sh \
+     --session SESSION --root PROJECT_ROOT
+   ```
+
+2. Open that terminal in Codex with `codex_app__open_in_codex`, using target
+   `{ type: "terminal", sessionId: "SESSION_ID" }`. Prefer bottom placement
+   unless the user requested another layout.
+3. Tell the user the panel is a live, read-only orchestrator view. Do not mirror
+   its entire transcript into commentary.
+
+The follower validates the project root and attaches a tmux client with both
+`read-only` and `ignore-size` flags. It cannot send input to or resize the
+orchestrator or worker panes. Do not start it without a PTY or wait
+synchronously for it to exit.
+
+If the terminal-opening tool is unavailable, show a bounded snapshot instead:
+
+```bash
+tmux list-windows -t SESSION -F '#I:#W'
+tmux capture-pane -t "SESSION:orchestrator" -p -S -220
+```
+
+Treat the orchestrator pane as the delegation boundary. Ask the orchestrator to
+spawn, poll, inspect, or finalize its agents; do not drive those agents directly
+unless the user explicitly requests bypassing the orchestrator.
+
+## Safety
+
+- Do not translate a standalone subagent request into a tmux team.
+- Do not delete `PROJECT_ROOT/.multiagent`; it stores durable state.
+- Do not kill or replace an existing session with the same name.
+- Keep outside-root writes subject to the multiagent write policy.

.agents/skills/start-agent-team/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Start Agent Team"
+  short_description: "Launch teams with live orchestrator output"
+  default_prompt: "Use $start-agent-team to start an agent team and show its live orchestrator output in Codex."

.agents/skills/start-agent-team/scripts/follow_orchestrator.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SESSION=""
+ROOT=""
+
+usage() {
+  cat <<'USAGE'
+Usage: follow_orchestrator.sh --session NAME --root DIR
+
+Attach a read-only tmux client to the orchestrator window. Run this helper in
+a PTY-backed Codex terminal session so the live pane can be opened in the
+Codex desktop UI. Keystrokes cannot control or resize the tmux session.
+USAGE
+}
+
+die() {
+  echo "follow-orchestrator: $*" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session)
+      SESSION="${2:-}"
+      shift 2
+      ;;
+    --root)
+      ROOT="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+[[ -n "$SESSION" ]] || die "--session NAME is required"
+[[ -n "$ROOT" ]] || die "--root DIR is required"
+[[ -d "$ROOT" ]] || die "root does not exist or is not a directory: $ROOT"
+command -v tmux >/dev/null 2>&1 || die "missing required command: tmux"
+tmux has-session -t "$SESSION" 2>/dev/null || die "missing tmux session: $SESSION"
+tmux list-windows -t "$SESSION" -F '#W' | grep -Fxq orchestrator || \
+  die "session has no orchestrator window: $SESSION"
+
+if [[ -z "${TERM:-}" || "${TERM:-}" == "dumb" ]]; then
+  if infocmp xterm-256color >/dev/null 2>&1; then
+    export TERM=xterm-256color
+  else
+    die "terminal does not support a live tmux view"
+  fi
+fi
+
+ROOT="$(cd "$ROOT" && pwd -P)"
+pane_root="$(tmux display-message -p -t "$SESSION:orchestrator" '#{pane_current_path}')"
+[[ -d "$pane_root" ]] || die "orchestrator pane path is not a directory: $pane_root"
+pane_root="$(cd "$pane_root" && pwd -P)"
+[[ "$pane_root" == "$ROOT" ]] || \
+  die "orchestrator root mismatch: expected $ROOT, found $pane_root"
+
+exec tmux attach-session -r -f ignore-size -t "$SESSION:orchestrator"