shellmates 0.1.0

package/lib/utils/config.js

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+export const CONFIG_DIR = join(homedir(), '.shellmates')
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json')
+export const INBOX_DIR = join(CONFIG_DIR, 'inbox')
+
+const DEFAULTS = {
+  permission_mode: 'default',
+  default_agent: 'gemini',
+  orchestrator: 'claude',
+}
+
+export function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return { ...DEFAULTS }
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf8')
+    return { ...DEFAULTS, ...JSON.parse(raw) }
+  } catch {
+    return { ...DEFAULTS }
+  }
+}
+
+export function writeConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  // Strip internal _docs key before writing user-facing config
+  const { _docs, ...clean } = config
+  writeFileSync(CONFIG_PATH, JSON.stringify(clean, null, 2) + '\n')
+}
+
+export function ensureDirs() {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  mkdirSync(INBOX_DIR, { recursive: true })
+}

package/lib/utils/logo.js

@@ -0,0 +1,84 @@
+import chalk from 'chalk'
+
+// Pixel grid definitions — 1 = filled block, 0 = empty
+// 3 pixels wide × 5 pixels tall per letter (compact, fits 80-char terminals)
+// Each pixel renders as '██' (2 chars), gap between letters = '  ' (1 empty pixel)
+
+const LETTERS = {
+  S: [
+    [1,1,1],
+    [1,0,0],
+    [1,1,1],
+    [0,0,1],
+    [1,1,1],
+  ],
+  H: [
+    [1,0,1],
+    [1,0,1],
+    [1,1,1],
+    [1,0,1],
+    [1,0,1],
+  ],
+  E: [
+    [1,1,1],
+    [1,0,0],
+    [1,1,0],
+    [1,0,0],
+    [1,1,1],
+  ],
+  L: [
+    [1,0,0],
+    [1,0,0],
+    [1,0,0],
+    [1,0,0],
+    [1,1,1],
+  ],
+  M: [
+    [1,0,1],
+    [1,1,1],
+    [1,0,1],
+    [1,0,1],
+    [1,0,1],
+  ],
+  A: [
+    [0,1,0],
+    [1,0,1],
+    [1,1,1],
+    [1,0,1],
+    [1,0,1],
+  ],
+  T: [
+    [1,1,1],
+    [0,1,0],
+    [0,1,0],
+    [0,1,0],
+    [0,1,0],
+  ],
+}
+
+// SHELLMATES = S H E L L M A T E S
+const WORD = ['S','H','E','L','L','M','A','T','E','S']
+
+const FILLED = chalk.hex('#4FC3F7')('██')
+const EMPTY  = '  '
+
+export function printLogo(version) {
+  const numRows = 5
+  const rows = Array.from({ length: numRows }, (_, rowIdx) => {
+    return WORD.map(ch => {
+      const grid = LETTERS[ch]
+      return grid[rowIdx].map(p => p ? FILLED : EMPTY).join('')
+    }).join(EMPTY) // 1-pixel gap between letters
+  })
+
+  const pad = '  '
+  console.log('')
+  for (const row of rows) {
+    console.log(pad + row)
+  }
+  console.log('')
+  if (version) {
+    console.log(pad + chalk.dim(`v${version}  ·  tmux multi-agent orchestration`))
+  }
+  console.log('')
+}

package/lib/utils/tmux.js

@@ -0,0 +1,46 @@
+import { execSync, spawnSync } from 'child_process'
+import { readdirSync, existsSync } from 'fs'
+
+export function tmuxAvailable() {
+  try {
+    execSync('which tmux', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function listSessions() {
+  try {
+    const out = execSync('tmux list-sessions -F "#{session_name}"', { encoding: 'utf8' })
+    return out.trim().split('\n').filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+export function sessionExists(name) {
+  return listSessions().includes(name)
+}
+
+export function listInboxFiles(inboxDir) {
+  if (!existsSync(inboxDir)) return []
+  return readdirSync(inboxDir).filter(f => f.endsWith('.txt'))
+}
+
+export function killSession(name) {
+  try {
+    execSync(`tmux kill-session -t ${name}`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function runScript(scriptPath, args = [], { inherit = true } = {}) {
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    stdio: inherit ? 'inherit' : 'pipe',
+    encoding: 'utf8',
+  })
+  return result
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "shellmates",
+  "version": "0.1.0",
+  "description": "Seamless tmux multi-agent orchestration for Claude, Gemini, and Codex",
+  "keywords": [
+    "tmux",
+    "ai",
+    "agents",
+    "claude",
+    "gemini",
+    "codex",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/rs07-git/shellmates",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rs07-git/shellmates.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "shellmates": "bin/shellmates.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "inquirer": "^9.3.7",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.1"
+  }
+}

package/scripts/dispatch.sh

@@ -0,0 +1,331 @@
+#!/usr/bin/env bash
+# dispatch.sh — Reliably send a task to a sub-agent pane
+#
+# Fixes addressed:
+#   1. Startup timing: waits for agent prompt to be ready before sending
+#   2. Permission prompts: enables auto-edit mode (Shift+Tab) before dispatching
+#   3. Token efficiency: prepends agent communication protocol header to every task
+#   4. Completion notification: starts background watcher + writes to inbox file
+#   5. Session visibility: shows or opens a live view of the worker after dispatch
+#
+# Usage:
+#   bash scripts/dispatch.sh --pane %46 --task-file /tmp/task.txt
+#   bash scripts/dispatch.sh --pane %46 --task "one-liner task"
+#   bash scripts/dispatch.sh --pane orchestra:0.0 --task-file /tmp/task.txt --no-ping
+#
+# Options:
+#   --pane        Target pane (stable %ID or positional session:0.0)
+#   --task-file   Path to task file (preferred for multi-step tasks)
+#   --task        Inline task (for simple one-liners)
+#   --job-id      Job ID for inbox result file (default: auto-generated)
+#   --ping-back   Pane to notify when done (default: caller's $TMUX_PANE)
+#   --task-name   Short label for status display
+#   --no-ping     Skip ping-back / inbox watcher (fire-and-forget)
+#   --no-view     Don't show/open the session viewer after dispatch
+#   --no-header   Skip prepending the agent communication protocol header
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HEADER_FILE="${SCRIPT_DIR}/../templates/task-header.txt"
+INBOX_DIR="${HOME}/.shellmates/inbox"
+PROJECT_TASKS_DIR=""   # set to project-relative path once we know the pane's cwd
+
+PANE=""
+TASK_FILE=""
+TASK_INLINE=""
+JOB_ID=""
+PING_BACK_PANE=""
+TASK_NAME=""
+NO_PING=false
+NO_VIEW=false
+NO_HEADER=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --pane)       PANE="$2"; shift 2 ;;
+    --task-file)  TASK_FILE="$2"; shift 2 ;;
+    --task)       TASK_INLINE="$2"; shift 2 ;;
+    --job-id)     JOB_ID="$2"; shift 2 ;;
+    --ping-back)  PING_BACK_PANE="$2"; shift 2 ;;
+    --task-name)  TASK_NAME="$2"; shift 2 ;;
+    --no-ping)    NO_PING=true; shift ;;
+    --no-view)    NO_VIEW=true; shift ;;
+    --no-header)  NO_HEADER=false; shift ;;  # reserved
+    -h|--help)
+      sed -n '2,20p' "$0" | sed 's/^# //' | sed 's/^#//'
+      exit 0 ;;
+    *) echo "ERROR: Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# ── Validate ──────────────────────────────────────────────────────────────────
+
+if [[ -z "$PANE" ]]; then
+  echo "ERROR: --pane is required"
+  exit 1
+fi
+
+if [[ -z "$TASK_FILE" && -z "$TASK_INLINE" ]]; then
+  echo "ERROR: --task-file or --task is required"
+  exit 1
+fi
+
+# ── Resolve ping-back pane ────────────────────────────────────────────────────
+
+if [[ -z "$PING_BACK_PANE" && "$NO_PING" == "false" ]]; then
+  if [[ -n "${TMUX_PANE:-}" ]]; then
+    PING_BACK_PANE="$TMUX_PANE"
+  elif [[ -n "${TMUX:-}" ]]; then
+    PING_BACK_PANE=$(tmux display-message -p '#{pane_id}' 2>/dev/null || echo "")
+  fi
+
+  if [[ -z "$PING_BACK_PANE" ]]; then
+    echo "NOTE: Not inside tmux — ping-back via tmux disabled."
+    echo "  Inbox watcher will still write to ~/.shellmates/inbox/"
+    echo "  Pass --ping-back PANE_ID to enable active notification."
+  fi
+fi
+
+# ── Preflight: verify pane is running an agent ────────────────────────────────
+
+PANE_CMD=$(tmux display-message -p -t "$PANE" '#{pane_current_command}' 2>/dev/null || echo "unknown")
+SHELL_CMDS=("bash" "zsh" "sh" "fish")
+
+for SHELL_CMD in "${SHELL_CMDS[@]}"; do
+  if [[ "$PANE_CMD" == "$SHELL_CMD" ]]; then
+    echo "ERROR: Pane $PANE is running $PANE_CMD — no agent detected."
+    echo "  Start the agent first: tmux send-keys -t $PANE 'gemini' Enter"
+    exit 1
+  fi
+done
+
+echo "Target pane: $PANE (process: $PANE_CMD)"
+
+# Resolve the pane's working directory (used to place task files inside the project)
+PANE_CWD=$(tmux display-message -p -t "$PANE" '#{pane_current_path}' 2>/dev/null || echo "/tmp")
+PROJECT_TASKS_DIR="${PANE_CWD}/.shellmates/tasks"
+
+# ── Wait for agent prompt and dismiss startup banner ──────────────────────────
+# Gemini shows a startup banner AFTER the initial prompt appears.
+# If we send the task immediately after seeing "Type your message", the banner
+# appears and steals the Enter keystroke — task never submits.
+# Fix: explicitly detect and dismiss the banner before dispatching.
+
+wait_for_prompt() {
+  local pane="$1"
+  local max_wait=20
+  local elapsed=0
+  echo -n "Waiting for agent prompt..."
+  while [[ $elapsed -lt $max_wait ]]; do
+    local output
+    output=$(tmux capture-pane -t "$pane" -p 2>/dev/null)
+    if echo "$output" | grep -q "Type your message"; then
+      echo " ready."
+      return 0
+    fi
+    sleep 1
+    elapsed=$((elapsed + 1))
+  done
+  echo " (timeout — proceeding anyway)"
+}
+
+dismiss_startup_banner() {
+  local pane="$1"
+  local output
+  output=$(tmux capture-pane -t "$pane" -p 2>/dev/null)
+  # Gemini shows an announcement banner with "What's Changing" or similar
+  if echo "$output" | grep -qE "What's Changing|We're making changes|Read more:.*goo\.gle"; then
+    echo "Dismissing startup banner..."
+    tmux send-keys -t "$pane" "" Enter
+    sleep 1
+    # Wait for prompt to reappear after dismiss
+    wait_for_prompt "$pane"
+  fi
+}
+
+# Verify the pane's input bar contains the expected string.
+# Returns 0 if found, 1 if not.
+input_bar_contains() {
+  local pane="$1"
+  local expected="$2"
+  tmux capture-pane -t "$pane" -p 2>/dev/null | grep -qF "$expected"
+}
+
+# Ensure a string is in the input bar before submitting. If the banner
+# cleared it (by consuming @filepath or the prior Enter), re-type it.
+ensure_input_ready() {
+  local pane="$1"
+  local text="$2"
+  local max_retries=3
+  local attempt=0
+
+  while [[ $attempt -lt $max_retries ]]; do
+    if input_bar_contains "$pane" "$text"; then
+      echo "Input verified: $(basename "$text" 2>/dev/null || echo "$text")"
+      return 0
+    fi
+
+    attempt=$((attempt + 1))
+    echo "Input bar missing expected text (attempt $attempt) — re-typing..."
+    # Clear whatever might be half-typed and retype
+    tmux send-keys -t "$pane" "C-c" 2>/dev/null || true
+    sleep 0.2
+    wait_for_prompt "$pane"
+    dismiss_startup_banner "$pane"
+    tmux send-keys -t "$pane" "$text"
+    sleep 0.4
+  done
+
+  echo "WARNING: Could not verify input bar after $max_retries attempts — submitting anyway"
+}
+
+wait_for_prompt "$PANE"
+dismiss_startup_banner "$PANE"
+
+# ── Enable auto-edit mode if not already in bypass mode ──────────────────────
+# If the agent was NOT started with --yolo/--full-auto (i.e. permission_mode=default),
+# send Shift+Tab to at least enable auto-edit for this session (approves file tools).
+# If bypass mode is active, the agent already handles this at startup — skip it.
+
+CONFIG_FILE="${HOME}/.shellmates/config.json"
+PERMISSION_MODE=$(python3 -c "
+import json, os
+cfg = '${CONFIG_FILE}'
+if os.path.exists(cfg):
+    d = json.load(open(cfg))
+    print(d.get('permission_mode', 'default'))
+else:
+    print('default')
+" 2>/dev/null || echo "default")
+
+if [[ "$PERMISSION_MODE" != "bypass" ]]; then
+  if [[ "$PANE_CMD" == "node" || "$PANE_CMD" == "gemini" ]]; then
+    # Gemini: Shift+Tab toggles auto-edit (approves file read/write tools)
+    tmux send-keys -t "$PANE" "BTab"
+    sleep 0.3
+  fi
+fi
+
+# ── Build final task file ─────────────────────────────────────────────────────
+
+# Resolve inline task to file
+TEMP_TASK_FILE=""
+if [[ -n "$TASK_INLINE" ]]; then
+  TEMP_TASK_FILE="/tmp/.shellmates-task-$$.txt"
+  echo "$TASK_INLINE" > "$TEMP_TASK_FILE"
+  TASK_FILE="$TEMP_TASK_FILE"
+fi
+
+# Auto-generate job ID
+if [[ -z "$JOB_ID" ]]; then
+  JOB_ID="job-$$-$(date +%s)"
+fi
+
+# Auto-generate task name
+if [[ -z "$TASK_NAME" ]]; then
+  TASK_NAME=$(grep -m1 '.' "$TASK_FILE" | sed 's/^#* *//' | cut -c1-60)
+fi
+
+# Build the final task: header + original task + completion footer
+# Place the file INSIDE the project dir so agents don't need a separate
+# permission prompt to read it (Gemini --yolo still prompts for /tmp reads).
+mkdir -p "$PROJECT_TASKS_DIR" 2>/dev/null || true
+if [[ -d "$PROJECT_TASKS_DIR" ]]; then
+  FINAL_TASK_FILE="${PROJECT_TASKS_DIR}/.dispatch-$$.txt"
+else
+  FINAL_TASK_FILE="/tmp/.shellmates-dispatch-$$.txt"
+fi
+mkdir -p "$INBOX_DIR"
+
+{
+  # Token efficiency protocol header
+  if [[ -f "$HEADER_FILE" ]]; then
+    cat "$HEADER_FILE"
+    echo ""
+  fi
+
+  # Original task content
+  cat "$TASK_FILE"
+
+  # Completion footer: write result to inbox file
+  cat << FOOTER
+
+---
+When your task is complete, write your result to this file:
+  ${INBOX_DIR}/${JOB_ID}.txt
+
+Use this exact format (concise — no prose):
+\`\`\`
+AGENT: $(echo "$PANE_CMD" | tr '[:upper:]' '[:lower:]')
+JOB: ${JOB_ID}
+STATUS: complete
+CHANGED: <comma-separated file paths, or none>
+RESULT: <≤5 line summary of what was done>
+\`\`\`
+
+Write the file with:
+  mkdir -p "${INBOX_DIR}" && cat > "${INBOX_DIR}/${JOB_ID}.txt" << 'EOF'
+AGENT: gemini
+JOB: ${JOB_ID}
+STATUS: complete
+CHANGED: <files>
+RESULT: <summary>
+EOF
+
+Then output: PHASE_COMPLETE: ${TASK_NAME}
+FOOTER
+} > "$FINAL_TASK_FILE"
+
+# Cleanup inline temp file
+[[ -n "$TEMP_TASK_FILE" ]] && rm -f "$TEMP_TASK_FILE"
+
+# ── Dispatch ──────────────────────────────────────────────────────────────────
+
+if [[ "$PANE_CMD" == "node" || "$PANE_CMD" == "gemini" ]]; then
+  echo "Dispatching via @filepath (Gemini CLI)..."
+  # Type the filepath but don't submit yet — Gemini may re-show the startup
+  # banner between the @filepath and the Enter. We:
+  #   1. Type the @filepath (no Enter)
+  #   2. Dismiss any banner that appeared
+  #   3. Verify the input bar still contains the filepath (re-type if not)
+  #   4. Submit
+  tmux send-keys -t "$PANE" "@${FINAL_TASK_FILE}"
+  sleep 0.5
+  dismiss_startup_banner "$PANE"
+  ensure_input_ready "$PANE" "@${FINAL_TASK_FILE}"
+  tmux send-keys -t "$PANE" "" Enter
+else
+  echo "Dispatching via direct send..."
+  tmux send-keys -t "$PANE" "$(cat "$FINAL_TASK_FILE")"
+  tmux send-keys -t "$PANE" "" Enter
+fi
+
+echo "Task dispatched: '${TASK_NAME}'"
+echo "Job ID: ${JOB_ID}"
+echo "Result will appear in: ${INBOX_DIR}/${JOB_ID}.txt"
+
+# ── Start background watcher ──────────────────────────────────────────────────
+
+if [[ "$NO_PING" == "false" ]]; then
+  WATCH_ARGS="$JOB_ID"
+  [[ -n "$PING_BACK_PANE" ]] && WATCH_ARGS="$WATCH_ARGS $PING_BACK_PANE"
+
+  bash "$SCRIPT_DIR/watch-inbox.sh" $WATCH_ARGS &
+  WATCHER_PID=$!
+  echo "Background watcher started (PID: $WATCHER_PID)"
+fi
+
+# ── Show session view ─────────────────────────────────────────────────────────
+
+if [[ "$NO_VIEW" == "false" ]]; then
+  SESSION=$(tmux display-message -p -t "$PANE" '#S' 2>/dev/null || echo "")
+  if [[ -n "$SESSION" ]]; then
+    echo ""
+    bash "$SCRIPT_DIR/view-session.sh" "$SESSION" "$PANE"
+  fi
+fi
+
+echo ""
+echo "Task file: $FINAL_TASK_FILE"
+echo "Monitor:   tmux capture-pane -t $PANE -p | tail -20"

package/scripts/launch-full-team.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# launch-full-team.sh — 4-pane multi-agent session
+#
+# Layout:
+#   ┌──────────────┬──────────────┐
+#   │  gemini-1    │   claude     │
+#   │  (worker A)  │ (orchestrat) │
+#   ├──────────────┼──────────────┤
+#   │  gemini-2    │   codex      │
+#   │  (worker B)  │  (executor)  │
+#   └──────────────┴──────────────┘
+#
+# Pane targets:
+#   full:0.0  — Gemini CLI worker A
+#   full:0.1  — Claude Code orchestrator
+#   full:0.2  — Gemini CLI worker B
+#   full:0.3  — Codex CLI executor
+#
+# Usage:
+#   ./scripts/launch-full-team.sh [--session name] [--dir path]
+
+set -euo pipefail
+
+SESSION="full"
+PROJECT_DIR="${PWD}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session) SESSION="$2"; shift 2 ;;
+    --dir)     PROJECT_DIR="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: $0 [--session name] [--dir path]"
+      exit 0 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "Session '$SESSION' already exists. Attaching..."
+  tmux attach-session -t "$SESSION"
+  exit 0
+fi
+
+echo "Creating 4-pane session '$SESSION'..."
+
+# Create and tile into 4 panes
+tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR"          # pane 0
+tmux split-window -h -t "$SESSION:0" -c "$PROJECT_DIR"       # pane 1 (right)
+tmux split-window -v -t "$SESSION:0.0" -c "$PROJECT_DIR"     # pane 2 (bottom-left)
+tmux split-window -v -t "$SESSION:0.1" -c "$PROJECT_DIR"     # pane 3 (bottom-right)
+
+# Label panes
+tmux select-pane -t "$SESSION:0.0" -T "gemini-A"
+tmux select-pane -t "$SESSION:0.1" -T "orchestrator (claude)"
+tmux select-pane -t "$SESSION:0.2" -T "gemini-B"
+tmux select-pane -t "$SESSION:0.3" -T "codex"
+
+# Start sub-agents
+tmux send-keys -t "$SESSION:0.0" "gemini" Enter
+tmux send-keys -t "$SESSION:0.2" "gemini" Enter
+tmux send-keys -t "$SESSION:0.3" "codex" Enter
+
+# Start orchestrator last
+sleep 1
+tmux send-keys -t "$SESSION:0.1" "claude" Enter
+
+tmux select-pane -t "$SESSION:0.1"
+
+echo ""
+echo "4-pane session ready."
+echo "  Pane 0.0 — Gemini worker A"
+echo "  Pane 0.1 — Claude orchestrator"
+echo "  Pane 0.2 — Gemini worker B"
+echo "  Pane 0.3 — Codex executor"
+echo ""
+
+tmux attach-session -t "$SESSION"