shellmates 0.1.0

package/scripts/status.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# status.sh — Show all shellmates sessions with their current state
+#
+# Usage:
+#   ./scripts/status.sh           # Show all sessions
+#   ./scripts/status.sh --json    # Machine-readable JSON output
+
+set -euo pipefail
+
+MANIFEST_FILE="${HOME}/.shellmates/sessions.json"
+JSON_MODE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=true; shift ;;
+    -h|--help) echo "Usage: $0 [--json]"; exit 0 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Collect all tmux session names
+ALL_TMUX_SESSIONS=$(tmux list-sessions -F '#{session_name}' 2>/dev/null || true)
+
+if [[ -z "$ALL_TMUX_SESSIONS" ]]; then
+  echo "No tmux sessions running."
+  exit 0
+fi
+
+# Build and print the session status table using Python
+python3 - <<PYEOF
+import json
+import os
+import subprocess
+import datetime
+
+manifest_file = "$MANIFEST_FILE"
+json_mode = $( [[ "$JSON_MODE" == "true" ]] && echo "True" || echo "False" )
+
+# Load manifest
+manifest_sessions = {}
+if os.path.exists(manifest_file):
+  try:
+    with open(manifest_file) as f:
+      data = json.load(f)
+    for s in data.get("sessions", []):
+      manifest_sessions[s["name"]] = s
+  except Exception:
+    pass
+
+# Get all live tmux sessions
+try:
+  raw = subprocess.check_output(
+    ["tmux", "list-sessions", "-F", "#{session_name}|#{session_created}"],
+    stderr=subprocess.DEVNULL, text=True
+  ).strip()
+  tmux_sessions = {}
+  for line in raw.splitlines():
+    parts = line.split("|", 1)
+    name = parts[0]
+    created_ts = int(parts[1]) if len(parts) > 1 else 0
+    tmux_sessions[name] = created_ts
+except Exception:
+  tmux_sessions = {}
+
+# Combine: manifest entries + any live sessions not in manifest
+all_names = list(manifest_sessions.keys())
+for name in tmux_sessions:
+  if name not in all_names:
+    all_names.append(name)
+
+if not all_names:
+  print("No shellmates sessions found.")
+  exit()
+
+def get_pane_cmd(pane_id):
+  """Check what process is running in a specific pane (by stable pane ID like %12)."""
+  try:
+    result = subprocess.check_output(
+      ["tmux", "display-message", "-p", "-t", pane_id, "#{pane_current_command}"],
+      stderr=subprocess.DEVNULL, text=True
+    ).strip()
+    return result
+  except Exception:
+    return "?"
+
+def age_str(ts):
+  if ts == 0:
+    return "unknown"
+  delta = datetime.datetime.now() - datetime.datetime.fromtimestamp(ts)
+  days = delta.days
+  hours = delta.seconds // 3600
+  minutes = (delta.seconds % 3600) // 60
+  if days > 0:
+    return f"{days}d ago"
+  elif hours > 0:
+    return f"{hours}h ago"
+  else:
+    return f"{minutes}m ago"
+
+def infer_status(entry, is_alive):
+  """Return a human-readable status for the session."""
+  if not is_alive:
+    return "dead (tmux gone)"
+  panes = entry.get("panes", {})
+  if not panes:
+    return "alive (no pane info)"
+  statuses = []
+  shell_cmds = {"bash", "zsh", "sh", "fish", "?"}
+  for role, pane_id in panes.items():
+    cmd = get_pane_cmd(pane_id)
+    if cmd in shell_cmds:
+      statuses.append(f"{role} idle")
+    else:
+      statuses.append(f"{role} active ({cmd})")
+  return ", ".join(statuses)
+
+rows = []
+for idx, name in enumerate(all_names, 1):
+  is_alive = name in tmux_sessions
+  entry = manifest_sessions.get(name, {})
+  created_ts = tmux_sessions.get(name, 0)
+
+  purpose = entry.get("purpose", "(no manifest entry)")
+  project = entry.get("project_dir", "—")
+  project_short = project.replace(os.environ.get("HOME", ""), "~")
+  agents = ", ".join(entry.get("agents", ["?"])) if entry else "?"
+  status = infer_status(entry, is_alive) if entry else ("alive" if is_alive else "dead")
+  age = age_str(created_ts)
+
+  rows.append({
+    "idx": idx,
+    "name": name,
+    "purpose": purpose,
+    "project": project_short,
+    "agents": agents,
+    "status": status,
+    "age": age,
+    "is_alive": is_alive,
+    "has_manifest": bool(entry)
+  })
+
+if json_mode:
+  print(json.dumps(rows, indent=2))
+else:
+  print("Shellmates sessions:\n")
+  fmt = "  {idx:<3}  {name:<16}  {purpose:<28}  {project:<30}  {agents:<8}  {age:<10}  {status}"
+  header = fmt.format(idx="#", name="name", purpose="purpose", project="project",
+                      agents="agents", age="age", status="status")
+  print(header)
+  print("  " + "─" * (len(header) - 2))
+  for r in rows:
+    marker = "" if r["is_alive"] else " [dead]"
+    manifest_note = "" if r["has_manifest"] else " *"
+    print(fmt.format(
+      idx=r["idx"],
+      name=r["name"] + marker,
+      purpose=r["purpose"] + manifest_note,
+      project=r["project"],
+      agents=r["agents"],
+      age=r["age"],
+      status=r["status"]
+    ))
+
+  print("")
+  if any(not r["has_manifest"] for r in rows):
+    print("  * Session not tracked by shellmates (started outside launch.sh)")
+  print("  To close sessions: bash scripts/teardown.sh")
+PYEOF

package/scripts/teardown.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# teardown.sh — Close shellmates sessions safely
+#
+# Shows all active sessions with context, then lets you choose which to close.
+# Never kills sessions automatically — always confirms first.
+#
+# Usage:
+#   ./scripts/teardown.sh         # Interactive: choose which sessions to close
+#   ./scripts/teardown.sh --all   # Close all shellmates sessions (skips per-session prompt)
+
+set -euo pipefail
+
+MANIFEST_FILE="${HOME}/.shellmates/sessions.json"
+KILL_ALL=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all) KILL_ALL=true; shift ;;
+    -h|--help)
+      echo "Usage: $0 [--all]"
+      echo "  --all   Close all sessions without per-session prompts"
+      exit 0 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Check if tmux is running at all
+if ! tmux list-sessions &>/dev/null 2>&1; then
+  echo "No tmux sessions running."
+  exit 0
+fi
+
+# Build session list via status.sh --json
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SESSION_JSON=$(bash "$SCRIPT_DIR/status.sh" --json 2>/dev/null || echo "[]")
+
+SESSION_COUNT=$(python3 -c "import json,sys; data=json.loads('$( echo "$SESSION_JSON" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" )'); print(len(data))" 2>/dev/null || echo "0")
+
+if [[ "$SESSION_COUNT" == "0" ]]; then
+  echo "No sessions found."
+  exit 0
+fi
+
+# Display sessions and collect kill list
+python3 - <<PYEOF
+import json, os, subprocess, sys
+
+manifest_file = "$MANIFEST_FILE"
+kill_all = $( [[ "$KILL_ALL" == "true" ]] && echo "True" || echo "False" )
+
+# Re-read sessions
+try:
+  raw = subprocess.check_output(
+    ["tmux", "list-sessions", "-F", "#{session_name}|#{session_created}"],
+    stderr=subprocess.DEVNULL, text=True
+  ).strip()
+  live_sessions = {line.split("|")[0] for line in raw.splitlines() if line}
+except Exception:
+  live_sessions = set()
+
+manifest_sessions = {}
+if os.path.exists(manifest_file):
+  try:
+    with open(manifest_file) as f:
+      data = json.load(f)
+    for s in data.get("sessions", []):
+      manifest_sessions[s["name"]] = s
+  except Exception:
+    pass
+
+# Build list: manifest first, then untracked live sessions
+all_names = list(manifest_sessions.keys())
+for name in live_sessions:
+  if name not in all_names:
+    all_names.append(name)
+
+if not all_names:
+  print("No sessions found.")
+  sys.exit(0)
+
+import datetime
+def age_str(ts):
+  if ts == 0: return "unknown"
+  delta = datetime.datetime.now() - datetime.datetime.fromtimestamp(ts)
+  d, h, m = delta.days, delta.seconds//3600, (delta.seconds%3600)//60
+  return f"{d}d" if d > 0 else (f"{h}h" if h > 0 else f"{m}m")
+
+# Get tmux created times
+try:
+  raw2 = subprocess.check_output(
+    ["tmux", "list-sessions", "-F", "#{session_name}|#{session_created}"],
+    stderr=subprocess.DEVNULL, text=True
+  ).strip()
+  created_map = {}
+  for line in raw2.splitlines():
+    parts = line.split("|")
+    if len(parts) == 2:
+      created_map[parts[0]] = int(parts[1])
+except Exception:
+  created_map = {}
+
+print("\nShellmates sessions:\n")
+rows = []
+for idx, name in enumerate(all_names, 1):
+  is_alive = name in live_sessions
+  entry = manifest_sessions.get(name, {})
+  purpose = entry.get("purpose", "(untracked)")
+  project = entry.get("project_dir", "—").replace(os.environ.get("HOME", ""), "~")
+  agents = ", ".join(entry.get("agents", ["?"])) if entry else "?"
+  ts = created_map.get(name, 0)
+  age = age_str(ts)
+  alive_str = "alive" if is_alive else "dead"
+  print(f"  [{idx}] {name:<16}  {purpose:<30}  {project:<28}  {agents:<8}  {age:<6}  {alive_str}")
+  rows.append({"idx": idx, "name": name, "is_alive": is_alive})
+
+print("")
+
+if kill_all:
+  to_kill = [r["name"] for r in rows if r["is_alive"]]
+  print(f"--all flag set. Closing {len(to_kill)} session(s): {', '.join(to_kill)}")
+  # Write kill list for bash to read
+  with open("/tmp/.shellmates_kill_list", "w") as f:
+    f.write("\n".join(to_kill))
+  sys.exit(0)
+
+print("Which sessions would you like to close?")
+print("  Enter numbers separated by spaces, 'all' to close all alive sessions,")
+print("  or press Enter to cancel: ", end="", flush=True)
+
+try:
+  response = input().strip().lower()
+except (EOFError, KeyboardInterrupt):
+  print("\nCancelled.")
+  sys.exit(0)
+
+if not response:
+  print("Cancelled.")
+  sys.exit(0)
+
+if response == "all":
+  to_kill = [r["name"] for r in rows if r["is_alive"]]
+else:
+  to_kill = []
+  for part in response.split():
+    try:
+      idx = int(part)
+      match = next((r for r in rows if r["idx"] == idx), None)
+      if match:
+        if match["is_alive"]:
+          to_kill.append(match["name"])
+        else:
+          print(f"  Session [{idx}] {match['name']} is already dead — skipping.")
+      else:
+        print(f"  Unknown number: {part}")
+    except ValueError:
+      print(f"  Skipping invalid input: {part}")
+
+if not to_kill:
+  print("Nothing to close.")
+  sys.exit(0)
+
+# Write kill list for bash to read
+with open("/tmp/.shellmates_kill_list", "w") as f:
+  f.write("\n".join(to_kill))
+
+print(f"\nClosing: {', '.join(to_kill)}")
+PYEOF
+
+# Read the kill list and execute
+if [[ ! -f /tmp/.shellmates_kill_list ]]; then
+  exit 0
+fi
+
+KILL_LIST=$(cat /tmp/.shellmates_kill_list)
+rm -f /tmp/.shellmates_kill_list
+
+if [[ -z "$KILL_LIST" ]]; then
+  exit 0
+fi
+
+while IFS= read -r SESSION_NAME; do
+  [[ -z "$SESSION_NAME" ]] && continue
+
+  echo -n "  Closing '$SESSION_NAME'... "
+  if tmux kill-session -t "$SESSION_NAME" 2>/dev/null; then
+    echo "done"
+  else
+    echo "already gone"
+  fi
+
+  # Remove from manifest
+  if [[ -f "$MANIFEST_FILE" ]]; then
+    python3 - <<PYEOF2
+import json, os
+
+manifest_file = "$MANIFEST_FILE"
+session_name = "$SESSION_NAME"
+
+if os.path.exists(manifest_file):
+  with open(manifest_file) as f:
+    data = json.load(f)
+  data["sessions"] = [s for s in data.get("sessions", []) if s["name"] != session_name]
+  with open(manifest_file, "w") as f:
+    json.dump(data, f, indent=2)
+PYEOF2
+  fi
+
+done <<< "$KILL_LIST"
+
+echo ""
+echo "Done. Run 'bash scripts/status.sh' to verify."

package/scripts/view-session.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# view-session.sh — Open a live view of a shellmates worker session
+#
+# Handles three cases automatically:
+#   1. User is inside tmux → creates a new window in their session
+#   2. User is on macOS, not in tmux → opens iTerm2 or Terminal.app
+#   3. Fallback → prints the attach command prominently
+#
+# Usage:
+#   bash scripts/view-session.sh SESSION_NAME [PANE_ID]
+#   bash scripts/view-session.sh --list
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# List mode
+if [[ "${1:-}" == "--list" ]]; then
+  bash "$SCRIPT_DIR/status.sh"
+  exit 0
+fi
+
+SESSION="${1:-}"
+PANE="${2:-}"
+
+if [[ -z "$SESSION" ]]; then
+  echo "Usage: $0 SESSION_NAME"
+  echo "       $0 --list     # show all active sessions"
+  exit 1
+fi
+
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "ERROR: Session '$SESSION' not found."
+  echo "Active sessions:"
+  tmux list-sessions -F "  #{session_name}" 2>/dev/null || echo "  (none)"
+  exit 1
+fi
+
+# ── Case 1: Already inside tmux ───────────────────────────────────────────────
+if [[ -n "${TMUX:-}" ]]; then
+  CURRENT_SESSION=$(tmux display-message -p '#S')
+
+  # If the worker is already in our session, just switch to it
+  if [[ "$SESSION" == "$CURRENT_SESSION" ]]; then
+    if [[ -n "$PANE" ]]; then
+      tmux select-pane -t "$PANE"
+      echo "Switched to pane $PANE in current session."
+    else
+      echo "Already in session '$SESSION' — use Ctrl+b [arrow] to navigate panes."
+    fi
+    exit 0
+  fi
+
+  # Worker is in a different session — open it in a new window
+  tmux new-window -t "$CURRENT_SESSION" \; \
+    send-keys -t "$CURRENT_SESSION" "tmux attach -t $SESSION" Enter
+  echo "Opened '$SESSION' in a new tmux window."
+  echo "Navigate: Ctrl+b n (next window) / Ctrl+b p (prev window)"
+  exit 0
+fi
+
+# ── Case 2: macOS, not in tmux — try to open a terminal window ───────────────
+if command -v osascript &>/dev/null; then
+  # Try iTerm2 first (common for developers)
+  if osascript -e 'tell application "iTerm2" to get version' &>/dev/null 2>&1; then
+    osascript << APPLESCRIPT
+tell application "iTerm2"
+  activate
+  create window with default profile
+  tell current session of current window
+    write text "tmux attach -t $SESSION"
+  end tell
+end tell
+APPLESCRIPT
+    echo "Opened '$SESSION' in a new iTerm2 window."
+    exit 0
+  fi
+
+  # Try Terminal.app
+  if osascript -e 'tell application "Terminal" to get version' &>/dev/null 2>&1; then
+    osascript -e "tell application \"Terminal\" to do script \"tmux attach -t $SESSION\""
+    osascript -e 'tell application "Terminal" to activate'
+    echo "Opened '$SESSION' in a new Terminal.app window."
+    exit 0
+  fi
+fi
+
+# ── Case 3: Fallback — print prominently ─────────────────────────────────────
+CMD="tmux attach -t $SESSION"
+BORDER=$(printf '═%.0s' $(seq 1 $((${#CMD} + 6))))
+
+echo ""
+echo "  ╔${BORDER}╗"
+echo "  ║   ${CMD}   ║"
+echo "  ╚${BORDER}╝"
+echo ""
+echo "  Run the command above in a new terminal to watch your agents work."
+echo ""

package/scripts/watch-inbox.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# watch-inbox.sh — Background watcher for shellmates completion files
+#
+# Watches ~/.shellmates/inbox/ for result files. When one appears,
+# notifies the orchestrator (Claude) either via:
+#   - tmux send-keys (if orchestrator is in a tmux pane)
+#   - stdout (if orchestrator is polling or using asyncRewake hook)
+#
+# This is intended to run as a background process started by dispatch.sh.
+# When a result arrives, it wakes Claude automatically — no manual polling.
+#
+# Usage:
+#   bash scripts/watch-inbox.sh JOB_ID [NOTIFY_PANE]
+#
+#   JOB_ID       Unique ID for this job (matches the result filename)
+#   NOTIFY_PANE  tmux pane to notify (e.g. %47). If omitted, uses $TMUX_PANE.
+#
+# Exit codes (for asyncRewake hook integration):
+#   0  — completed cleanly (no asyncRewake)
+#   2  — result received (triggers asyncRewake if used as a hook)
+
+set -euo pipefail
+
+JOB_ID="${1:-}"
+NOTIFY_PANE="${2:-${TMUX_PANE:-}}"
+INBOX_DIR="${HOME}/.shellmates/inbox"
+RESULT_FILE="${INBOX_DIR}/${JOB_ID}.txt"
+TIMEOUT="${SHELLMATES_TIMEOUT:-300}"  # 5 minutes default
+INTERVAL=1
+ELAPSED=0
+
+if [[ -z "$JOB_ID" ]]; then
+  echo "Usage: $0 JOB_ID [NOTIFY_PANE]"
+  exit 1
+fi
+
+mkdir -p "$INBOX_DIR"
+
+# Wait for the result file
+while [[ ! -f "$RESULT_FILE" && $ELAPSED -lt $TIMEOUT ]]; do
+  sleep $INTERVAL
+  ELAPSED=$((ELAPSED + INTERVAL))
+done
+
+if [[ ! -f "$RESULT_FILE" ]]; then
+  MSG="SHELLMATES_TIMEOUT: job $JOB_ID timed out after ${TIMEOUT}s"
+  if [[ -n "$NOTIFY_PANE" ]]; then
+    tmux send-keys -t "$NOTIFY_PANE" "$MSG — AWAITING_INSTRUCTIONS" Enter 2>/dev/null || true
+  fi
+  echo "$MSG"
+  exit 1
+fi
+
+# Read the result
+RESULT=$(cat "$RESULT_FILE")
+SUMMARY=$(grep "^RESULT:" "$RESULT_FILE" -A 5 | tail -5 | tr '\n' ' ' | cut -c1-120)
+
+MSG="AGENT_PING: job:${JOB_ID} status:complete ${SUMMARY} — AWAITING_INSTRUCTIONS"
+
+# Notify the orchestrator
+if [[ -n "$NOTIFY_PANE" ]]; then
+  # Active notification: type directly into orchestrator's pane
+  tmux send-keys -t "$NOTIFY_PANE" "$MSG" Enter 2>/dev/null && {
+    echo "Notified pane $NOTIFY_PANE"
+    exit 2  # asyncRewake signal
+  }
+fi
+
+# Fallback: print to stdout (orchestrator polling or asyncRewake hook reads this)
+echo "$MSG"
+exit 2

package/templates/.codex/agents/default.toml

@@ -0,0 +1,5 @@
+developer_instructions = """
+You are a general-purpose coding agent. Research the codebase before making changes.
+Follow the project conventions in AGENTS.md and GEMINI.md.
+Commit after each logical unit of work. Signal PHASE_COMPLETE when done.
+"""

package/templates/.codex/agents/executor.toml

@@ -0,0 +1,7 @@
+developer_instructions = """
+You are an implementation specialist.
+Execute approved plan steps with the smallest defensible change set.
+Keep commits scoped to the current task.
+Provide verification evidence for each deliverable.
+Signal PHASE_COMPLETE with a summary of what changed and what was verified.
+"""

package/templates/.codex/agents/explorer.toml

@@ -0,0 +1,5 @@
+developer_instructions = """
+You are a codebase mapper. Read-only — do not edit files.
+Your job: given a task or file list, map dependencies, callers, and blast radius.
+Return a structured summary of what files are involved, what they do, and what could be affected by changes.
+"""

package/templates/.codex/agents/planner.toml

@@ -0,0 +1,6 @@
+developer_instructions = """
+You are a planning specialist.
+Your job: turn a task description and codebase context into a structured, executable plan.
+Output a markdown plan with: goal, file list, step-by-step tasks, and verification criteria.
+Do NOT implement — only plan. Hand the plan back to the orchestrator.
+"""

package/templates/.codex/agents/researcher.toml

@@ -0,0 +1,6 @@
+developer_instructions = """
+You are a research specialist. Read only — do not edit files.
+Your job: given a task, identify constraints, dependencies, and unknowns.
+Check the relevant docs, existing code patterns, and potential integration risks.
+Return a structured research report to the orchestrator.
+"""

package/templates/.codex/agents/reviewer.toml

@@ -0,0 +1,5 @@
+developer_instructions = """
+You are a code reviewer. Read-only — do not edit files.
+Review diffs and recent commits for correctness, security issues, regressions, and missing test coverage.
+Rank findings by severity. Return a structured review to the orchestrator.
+"""

package/templates/.codex/agents/verifier.toml

@@ -0,0 +1,6 @@
+developer_instructions = """
+You are an independent verification specialist. Read-only — do not edit files.
+Your job: given completed work, verify it against the original plan and UAT criteria.
+Run tests, check outputs, and report pass/fail with evidence.
+List any residual risks or gaps. Do not approve work that cannot be verified.
+"""

package/templates/.codex/agents/worker.toml

@@ -0,0 +1,5 @@
+developer_instructions = """
+You are a targeted execution worker.
+Implement a specific, well-scoped task as described in the prompt.
+Make the minimum necessary changes. Commit with a clear message. Return a summary.
+"""

package/templates/.codex/config.toml

@@ -0,0 +1,43 @@
+[features]
+multi_agent = true
+
+[agents]
+max_threads = 8
+max_depth = 1
+job_max_runtime_seconds = 2700
+
+# ── Built-in compatibility roles ──────────────────────────────────────────────
+
+[agents.default]
+description = "General-purpose fallback agent for planning, research, and execution."
+config_file = "agents/default.toml"
+
+[agents.explorer]
+description = "Read-only codebase mapper for scoping and dependency tracing before edits."
+config_file = "agents/explorer.toml"
+
+[agents.worker]
+description = "Execution worker for targeted implementation tasks under a validated plan."
+config_file = "agents/worker.toml"
+
+[agents.reviewer]
+description = "Read-only reviewer for regressions, risk, and missing verification evidence."
+config_file = "agents/reviewer.toml"
+
+# ── Specialized task roles ────────────────────────────────────────────────────
+
+[agents.planner]
+description = "Planning specialist — produces structured PLAN.md artifacts from context and research."
+config_file = "agents/planner.toml"
+
+[agents.researcher]
+description = "Research specialist — discovers constraints, docs, and integration unknowns before planning."
+config_file = "agents/researcher.toml"
+
+[agents.executor]
+description = "Implementation specialist — executes approved plans with minimal blast radius."
+config_file = "agents/executor.toml"
+
+[agents.verifier]
+description = "Independent verification specialist — runs tests, checks UAT criteria, reports residual risk."
+config_file = "agents/verifier.toml"