shellmates 0.1.0 → 0.1.3

package/README.md

@@ -1,131 +1,115 @@
 # shellmates
 
-Your terminal. Multiple AI models. All talking to each other.
+<div align="center">
+  <img src="docs/logo.png" alt="shellmates" width="720" />
+</div>
 
-```
-┌──────────────────────────┬──────────────────────────┬──────────────────────────┐
-│  claude                  │  gemini                  │  codex                   │
-│                          │                          │                          │
-│  Planning phase 3...     │  Reading the plan...     │  Reading the plan...     │
-│  Delegating to agents... │  Writing auth.py...      │  Writing tests...        │
-│  Waiting for signals...  │  Tests passing ✓         │  All passing ✓           │
-│  Nice. On to phase 4.    │  PHASE_COMPLETE: done    │  PHASE_COMPLETE: done    │
-└──────────────────────────┴──────────────────────────┴──────────────────────────┘
-```
-
-Claude plans. Gemini builds. Codex verifies. They coordinate through your terminal using nothing but tmux — no APIs between them, no glue code, just agents passing messages like coworkers at adjacent desks.
-
----
+<br />
 
-## What
+Your terminal. Multiple AI agents. All talking to each other.
 
-shellmates is a lightweight orchestration layer for your terminal. It connects Claude Code, Gemini CLI, and Codex in side-by-side tmux panes — Claude holds the plan and delegates, the others execute in parallel and signal back when done.
+```
+npm install -g shellmates
+```
 
-No new framework. No shared memory. No API calls between models. Just text in a terminal.
+Claude plans. Gemini builds. Codex verifies. They coordinate through your terminal using tmux — no APIs between them, no glue code, just agents passing tasks like coworkers at adjacent desks.
 
 ---
 
-## Why
-
-Every AI coding tool runs one model in one context. You hit a wall when the task gets big — context fills up, the model loses the thread, architectural decisions get buried in implementation noise.
-
-shellmates splits the work the way a good team does:
-
-- **One agent thinks.** Claude holds the plan, reviews the work, decides what's next. Uses [GSD](https://github.com/gsd-build/get-shit-done) to produce structured plans that sub-agents can execute without needing your entire conversation history.
-- **Other agents build.** Gemini and Codex get a fresh context, a clear plan, and a specific job. They commit, signal done, and wait.
-- **The terminal is the meeting room.** tmux `send-keys` delivers tasks. `capture-pane` reads the replies. That's the whole protocol.
+![shellmates demo](docs/demo.gif)
 
 ---
 
 ## How it works
 
 ```
-You describe what to build
-        ↓
-Claude plans it with /gsd:plan-phase  →  PLAN.md on disk
-        ↓
-Claude sends the plan to Gemini       →  tmux send-keys
-Claude sends the plan to Codex        →  tmux send-keys  (in parallel)
+shellmates spawn --task "Add dark mode" --agent gemini
         ↓
-Gemini implements, tests, commits
-Codex implements, tests, commits      (simultaneously)
+shellmates opens a tmux pane, launches Gemini, hands it the task
         ↓
-Both signal: PHASE_COMPLETE           →  Claude reads with capture-pane
+Gemini implements, tests, writes results to ~/.shellmates/inbox/
         ↓
-Claude reviews, decides next step
+Claude gets a native notification (no polling) → reads the result → decides what's next
         ↓
 repeat
 ```
 
-The plan lives on disk. Sub-agents read it fresh every time. No conversation history required, no context bleed between agents, no awkward handoffs.
+The agent runs in its own isolated tmux session. You stay in your pane. When it's done, Claude wakes up automatically via a PostToolUse hook — not because it kept checking.
 
 ---
 
-![shellmates demo](docs/demo.gif)
+## Get started
+
+```bash
+shellmates init          # create config and directories
+shellmates install-hook  # wire up native Claude Code notifications (do this once)
+shellmates config        # set your default agent and permission mode
+```
+
+Then dispatch a task:
+
+```bash
+shellmates spawn --task "Add dark mode to the settings page"
+shellmates spawn --task-file plan.md --agent codex --watch
+```
 
 ---
 
-## Get started
+## Commands
 
-**Point your AI agent at this:**
+| Command | What it does |
+|---|---|
+| `shellmates init` | First-time setup — create `~/.shellmates/` and default config |
+| `shellmates config` | Change default agent, orchestrator, and permission mode |
+| `shellmates spawn` | Dispatch a task to a worker agent in a new tmux session |
+| `shellmates status` | Show active sessions, config, and inbox results |
+| `shellmates install-hook` | Install the Claude Code PostToolUse hook for native notifications |
+| `shellmates teardown` | Kill shellmates tmux sessions |
+| `shellmates update` | Update to the latest version |
+
+**Spawn options:**
 
 ```
-Read https://raw.githubusercontent.com/rs07-git/shellmates/main/INIT.md and set up shellmates for this project.
+-t, --task <text>       Inline task text
+-f, --task-file <path>  Path to a task file
+-a, --agent <name>      gemini | codex (overrides default)
+-s, --session <name>    tmux session name
+-p, --project <path>    Working directory for the agent (default: cwd)
+-w, --watch             Wait and print result when agent finishes
 ```
 
-That's it. Your agent will install the tools, update your project files, fill in the config, and drop a personalized tutorial in your terminal. No manual steps required.
-
-> Works with Claude Code, Gemini CLI, Codex, or any AI that can read a URL and run shell commands.
-
 ---
 
-## Want to understand what's happening first?
+## The notification hook
 
-**→ [QUICKSTART.md](QUICKSTART.md)** — step-by-step walkthrough you can follow yourself
+Without the hook, Claude has to poll for results — checking the inbox every few seconds, burning tokens doing nothing useful.
 
----
+With `shellmates install-hook`, a PostToolUse hook script watches for inbox files in the background and uses Claude Code's `asyncRewake` mechanism to deliver a native notification when the agent finishes. Claude wakes up exactly once, reads the result, and moves on.
 
-## Mix and match
+```bash
+shellmates install-hook
+```
 
-| Orchestrator | Executor(s) | Good for |
-|---|---|---|
-| Claude | Gemini | Large context tasks, Google Search grounding |
-| Claude | Codex | Sandboxed execution, internal multi-agent roles |
-| Claude | Gemini + Codex | Parallel tracks — implement and verify simultaneously |
-| Claude | Multiple Gemini panes | Fan-out across many files at once |
+Run it once. It installs `~/.claude/hooks/shellmates-notify.sh` and adds the hook entry to `~/.claude/settings.json` automatically.
 
 ---
 
-## What's in the box
+## Mix and match
 
-```
-shellmates/
-├── INIT.md                ← agent-executable setup (point your AI here)
-├── QUICKSTART.md          ← human-readable setup guide
-├── ORCHESTRATOR.md        ← Claude's operating instructions (copied to your project)
-├── templates/
-│   ├── CLAUDE.md          ← snippet added to your project's CLAUDE.md
-│   ├── GEMINI.md          ← filled in and added to your project root
-│   ├── AGENTS.md          ← for Codex
-│   └── .codex/            ← Codex multi-agent role configs
-├── scripts/
-│   ├── launch.sh          ← spin up a 2-pane session
-│   ├── launch-full-team.sh ← spin up a 4-pane session
-│   └── monitor.sh         ← watch for signals in the background
-└── docs/
-    ├── WORKFLOW.md        ← the plan/execute split explained
-    ├── PROTOCOL.md        ← full tmux IPC reference
-    ├── ROLES.md           ← patterns and when to use each
-    └── TROUBLESHOOTING.md
-```
+| Orchestrator | Worker(s) | Good for |
+|---|---|---|
+| Claude Code | Gemini CLI | Large context tasks, long-running implementations |
+| Claude Code | Codex CLI | Sandboxed execution, isolated environments |
+| Claude Code | Gemini + Codex | Parallel tracks — build and verify simultaneously |
+| Claude Code | Multiple Gemini panes | Fan-out across many files or components |
 
 ---
 
-## The protocol in one paragraph
-
-Claude sends a task by running `tmux send-keys -t pane "do X" Enter`. The sub-agent does the work and prints `PHASE_COMPLETE: Phase N — summary` when done. Claude reads the output with `tmux capture-pane -t pane -p | tail -20`. No framework, no SDK, no shared state. Just text in a terminal.
+## Requirements
 
-Full spec in [docs/PROTOCOL.md](docs/PROTOCOL.md).
+- Node 18+
+- tmux
+- At least one of: [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex)
 
 ---
 

package/bin/shellmates.js

@@ -7,10 +7,62 @@ import { fileURLToPath } from 'url'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
 
+// ── Bare call or top-level --help/-h → custom welcome screen ─────────────────
+const args = process.argv.slice(2)
+const isWelcome = args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help'
+
+if (isWelcome) {
+  const chalk = (await import('chalk')).default
+  const { printLogo } = await import('../lib/utils/logo.js')
+  const { checkUpdate } = await import('../lib/utils/update-check.js')
+  const { existsSync } = await import('fs')
+  const { join: pathJoin } = await import('path')
+  const { homedir } = await import('os')
+
+  printLogo(pkg.version)
+
+  const cmd = (name, desc) =>
+    `  ${chalk.bold(name.padEnd(16))}${chalk.dim(desc)}`
+
+  console.log(chalk.dim('  COMMANDS'))
+  console.log(cmd('init',          'First-time setup — create config and directories'))
+  console.log(cmd('config',        'Configure agents, orchestrator, and permission mode'))
+  console.log(cmd('spawn',         'Dispatch a task to a worker agent in a new tmux session'))
+  console.log(cmd('status',        'Show active sessions and inbox results'))
+  console.log(cmd('install-hook',  'Wire up native Claude Code AGENT_PING notifications'))
+  console.log(cmd('teardown',      'Kill shellmates tmux sessions'))
+  console.log(cmd('update',        'Update shellmates to the latest version'))
+  console.log('')
+  console.log(chalk.dim('  EXAMPLES'))
+  console.log(`  ${chalk.dim('shellmates spawn --task "Add dark mode" --agent gemini')}`)
+  console.log(`  ${chalk.dim('shellmates spawn --task-file plan.md --watch')}`)
+  console.log(`  ${chalk.dim('shellmates status')}`)
+  console.log('')
+  console.log('  ' + chalk.dim('shellmates <command> --help') + chalk.dim(' for command details.'))
+  console.log('')
+
+  // First-run nudge
+  const configPath = pathJoin(homedir(), '.shellmates', 'config.json')
+  if (!existsSync(configPath)) {
+    console.log(chalk.yellow('  ~ Not set up yet.') + '  Run ' + chalk.bold('shellmates init') + ' to get started.')
+    console.log('')
+  }
+
+  // Update notice (non-blocking, cached — won't slow you down)
+  const update = await checkUpdate(pkg.version)
+  if (update) {
+    console.log(chalk.cyan(`  ✨ Update available: ${chalk.dim(update.current)} → ${chalk.bold(update.latest)}`))
+    console.log(chalk.dim('     shellmates update'))
+    console.log('')
+  }
+
+  process.exit(0)
+}
+
 program
   .name('shellmates')
   .description('Seamless tmux multi-agent orchestration')
-  .version(pkg.version)
+  .version(pkg.version, '-v, --version', 'Print version number')
 
 // ── shellmates init ──────────────────────────────────────────────────────────
 program
@@ -74,6 +126,15 @@ program
     await installHook(opts)
   })
 
+// ── shellmates update ────────────────────────────────────────────────────────
+program
+  .command('update')
+  .description('Update shellmates to the latest version')
+  .action(async () => {
+    const { update } = await import('../lib/commands/update.js')
+    await update()
+  })
+
 // ── shellmates teardown ──────────────────────────────────────────────────────
 program
   .command('teardown [session]')

package/lib/commands/config.js

@@ -1,36 +1,40 @@
 import chalk from 'chalk'
 import inquirer from 'inquirer'
 import { readConfig, writeConfig, ensureDirs } from '../utils/config.js'
+import { AGENTS } from '../utils/agents.js'
 
-const AGENT_CHOICES = [
-  { name: 'Gemini CLI  (google/gemini-cli)', value: 'gemini' },
-  { name: 'Codex CLI   (openai/codex)', value: 'codex' },
-  { name: 'Ask me each time', value: 'ask' },
-]
+const AGENT_CHOICES = Object.entries(AGENTS).map(([value, a]) => ({
+  name: `${a.label.padEnd(14)} ${chalk.dim(a.hint)}`,
+  value,
+}))
 
 const ORCHESTRATOR_CHOICES = [
-  { name: 'Claude Code  (this session)', value: 'claude' },
-  { name: 'Gemini CLI', value: 'gemini' },
-  { name: 'Codex CLI', value: 'codex' },
+  { name: `Claude Code   ${chalk.dim('(this session)')}`, value: 'claude' },
+  { name: `Gemini CLI    ${chalk.dim('gemini')}`, value: 'gemini' },
+  { name: `Codex CLI     ${chalk.dim('codex')}`, value: 'codex' },
 ]
 
 export async function config() {
   ensureDirs()
   const current = readConfig()
 
+  // Migrate old single-string format → array
+  const currentAgents = current.default_agents
+    || (current.default_agent ? [current.default_agent] : ['gemini'])
+
   console.log('')
   console.log(chalk.bold('  Shellmates — Settings'))
-  console.log(chalk.dim('  ────────────────────────────────────'))
-  console.log(chalk.dim(`  Current config: ~/.shellmates/config.json`))
+  console.log(chalk.dim('  ─────────────────────────────────────'))
   console.log('')
 
   const answers = await inquirer.prompt([
     {
-      type: 'list',
-      name: 'default_agent',
-      message: 'Default worker agent:',
+      type: 'checkbox',
+      name: 'default_agents',
+      message: 'Default worker agent(s):',
       choices: AGENT_CHOICES,
-      default: current.default_agent,
+      default: currentAgents,
+      validate: (ans) => ans.length > 0 || 'Select at least one agent.',
       prefix: ' ',
     },
     {
@@ -47,11 +51,11 @@ export async function config() {
       message: 'Permission mode:',
       choices: [
         {
-          name: 'default  — agents ask before modifying files or running commands',
+          name: `default  ${chalk.dim('— agents ask before modifying files or running commands')}`,
           value: 'default',
         },
         {
-          name: 'bypass   — agents run fully autonomously (gemini --yolo, codex --full-auto)',
+          name: `bypass   ${chalk.dim('— agents run fully autonomously (gemini --yolo, codex --full-auto)')}`,
           value: 'bypass',
         },
       ],
@@ -68,7 +72,6 @@ export async function config() {
     },
   ])
 
-  // If user chose bypass but didn't confirm, revert to default
   if (answers.permission_mode === 'bypass' && answers.bypass_confirmed === false) {
     answers.permission_mode = 'default'
     console.log('')
@@ -81,8 +84,8 @@ export async function config() {
   console.log('')
   console.log(chalk.green('  ✓') + ' Settings saved.')
   console.log('')
-  console.log(chalk.dim('  permission_mode: ') + chalk.bold(toSave.permission_mode))
-  console.log(chalk.dim('  default_agent:   ') + chalk.bold(toSave.default_agent))
+  console.log(chalk.dim('  default_agents:  ') + chalk.bold(toSave.default_agents.join(', ')))
   console.log(chalk.dim('  orchestrator:    ') + chalk.bold(toSave.orchestrator))
+  console.log(chalk.dim('  permission_mode: ') + chalk.bold(toSave.permission_mode))
   console.log('')
 }

package/lib/commands/init.js

@@ -1,21 +1,12 @@
 import chalk from 'chalk'
 import { existsSync } from 'fs'
-import { CONFIG_PATH, CONFIG_DIR, INBOX_DIR, readConfig, writeConfig, ensureDirs } from '../utils/config.js'
+import { CONFIG_PATH, writeConfig, ensureDirs } from '../utils/config.js'
 import { tmuxAvailable } from '../utils/tmux.js'
-import { printLogo } from '../utils/logo.js'
+import { checkAndInstallAgents } from '../utils/agents.js'
 
 export async function init({ force = false } = {}) {
-  const { readFileSync } = await import('fs')
-  const { join, dirname, fileURLToPath } = await import('path')
-  const { fileURLToPath: fu } = await import('url')
-  let version = '0.1.0'
-  try {
-    const __dirname = dirname(fu(import.meta.url))
-    const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'))
-    version = pkg.version
-  } catch {}
-
-  printLogo(version)
+  console.log('')
+  console.log(chalk.bold('  Shellmates — Setup'))
   console.log(chalk.dim('  ─────────────────────────────'))
   console.log('')
 
@@ -27,6 +18,11 @@ export async function init({ force = false } = {}) {
     process.exit(1)
   }
   console.log(chalk.green('  ✓') + ' tmux found')
+  console.log('')
+
+  // Agent detection + optional install
+  await checkAndInstallAgents()
+  console.log('')
 
   // Create dirs
   ensureDirs()
@@ -35,12 +31,12 @@ export async function init({ force = false } = {}) {
 
   // Config
   if (existsSync(CONFIG_PATH) && !force) {
-    console.log(chalk.yellow('  ~') + ` Config already exists at ${CONFIG_PATH}`)
+    console.log(chalk.yellow('  ~') + ` Config already exists`)
     console.log(chalk.dim('    Run with --force to reset, or use: shellmates config'))
   } else {
     writeConfig({
       permission_mode: 'default',
-      default_agent: 'gemini',
+      default_agents: ['gemini'],
       orchestrator: 'claude',
     })
     console.log(chalk.green('  ✓') + ` Config created at ${CONFIG_PATH}`)
@@ -50,7 +46,8 @@ export async function init({ force = false } = {}) {
   console.log(chalk.bold('  Ready.'))
   console.log('')
   console.log('  Next steps:')
-  console.log(chalk.dim('    shellmates config') + '  — configure agents and permission mode')
-  console.log(chalk.dim('    shellmates spawn') + '   — dispatch a task to a worker agent')
+  console.log(chalk.dim('    shellmates config') + '      — configure agents and permission mode')
+  console.log(chalk.dim('    shellmates install-hook') + ' — wire up native Claude notifications')
+  console.log(chalk.dim('    shellmates spawn') + '       — dispatch a task to a worker agent')
   console.log('')
 }

package/lib/commands/pond.js

@@ -0,0 +1,105 @@
+import chalk from 'chalk'
+import { writeFileSync, chmodSync, existsSync } from 'fs'
+import { join } from 'path'
+import { tmpdir, homedir } from 'os'
+import { execSync, spawnSync } from 'child_process'
+import { readConfig, CONFIG_PATH } from '../utils/config.js'
+import { tmuxAvailable } from '../utils/tmux.js'
+
+const ORCHESTRATOR_CMDS = {
+  claude: (promptFile) => `claude "$(cat ${promptFile})"`,
+  gemini: (promptFile) => `gemini -p "$(cat ${promptFile})"`,
+}
+
+function buildPrompt(agents, project) {
+  const agentList = agents.join(', ')
+  const projectNote = project ? `The user's project is at: ${project}` : ''
+
+  return `You are the shellmates orchestrator — a coordinating AI that helps users accomplish software development goals by delegating work to specialized AI agent executors.
+
+Your job is NOT to write code yourself. You plan, clarify, and dispatch.
+
+Start with a single warm, brief greeting and ask the user what they want to work on today. Keep it to one or two sentences — don't explain your role, just start the conversation naturally.
+
+When the user shares their goal:
+1. Ask clarifying questions if needed (scope, affected files, tech stack, constraints)
+2. Once you have enough context, break the work into discrete, self-contained tasks
+3. Dispatch each task using the Bash tool: shellmates spawn --task "precise task description" --agent <agent>
+4. When an executor finishes you'll receive an AGENT_PING in your terminal — review the result, then decide what comes next
+5. Repeat until the goal is complete
+
+Dispatch rules:
+- Only spawn when you have a specific, actionable task — not vague intentions
+- gemini: best for large-context work, long implementations, reading many files
+- codex: best for sandboxed execution, isolated environments, focused rewrites
+- You can dispatch multiple agents in parallel if tasks are truly independent
+- Never spawn the same task twice — verify before re-dispatching
+
+Available agents: ${agentList}
+Dispatch command: shellmates spawn --task "..." --agent gemini|codex
+Check sessions: shellmates status
+${projectNote}`
+}
+
+export async function pond(options) {
+  if (!existsSync(CONFIG_PATH)) {
+    console.log(chalk.yellow('\n  ~ Not initialized yet.'))
+    console.log('  Run ' + chalk.bold('shellmates init') + ' first.\n')
+    process.exit(1)
+  }
+
+  if (!tmuxAvailable()) {
+    console.log(chalk.red('\n  ✗ tmux not found. Install: brew install tmux\n'))
+    process.exit(1)
+  }
+
+  const config = readConfig()
+  const orchestrator = config.orchestrator || 'claude'
+  const agents = config.default_agents || (config.default_agent ? [config.default_agent] : ['gemini'])
+  const project = options.project || process.cwd()
+
+  if (!ORCHESTRATOR_CMDS[orchestrator]) {
+    console.log(chalk.red(`\n  ✗ Orchestrator "${orchestrator}" doesn't support pond mode yet.`))
+    console.log(chalk.dim('  Set orchestrator to "claude" in shellmates config.\n'))
+    process.exit(1)
+  }
+
+  const ts = Date.now()
+  const sessionName = options.session || `shellmates-pond-${ts}`
+
+  // Write prompt to temp file (avoids shell escaping issues)
+  const promptFile = join(tmpdir(), `shellmates-pond-${ts}.txt`)
+  writeFileSync(promptFile, buildPrompt(agents, project))
+
+  // Write launcher script
+  const launchFile = join(tmpdir(), `shellmates-pond-${ts}.sh`)
+  const orchCmd = ORCHESTRATOR_CMDS[orchestrator](promptFile)
+  writeFileSync(launchFile, `#!/bin/bash\ncd ${JSON.stringify(project)}\n${orchCmd}\n`)
+  chmodSync(launchFile, 0o755)
+
+  console.log('')
+  console.log(chalk.bold('  Shellmates — Pond'))
+  console.log(chalk.dim('  ─────────────────────────────────────'))
+  console.log(chalk.dim('  Orchestrator: ') + chalk.bold(orchestrator))
+  console.log(chalk.dim('  Agents:       ') + chalk.bold(agents.join(', ')))
+  console.log(chalk.dim('  Project:      ') + chalk.dim(project))
+  console.log(chalk.dim('  Session:      ') + chalk.dim(sessionName))
+  console.log('')
+  console.log(chalk.dim('  Starting pond... attach with Ctrl+A (or configured prefix)'))
+  console.log('')
+
+  // Create detached tmux session
+  try {
+    execSync(`tmux new-session -d -s ${JSON.stringify(sessionName)} -x 220 -y 50`, { stdio: 'ignore' })
+  } catch {
+    console.log(chalk.red(`  ✗ Could not create tmux session (already exists?)`))
+    console.log(chalk.dim(`    Try: tmux attach -t ${sessionName}\n`))
+    process.exit(1)
+  }
+
+  // Launch orchestrator
+  execSync(`tmux send-keys -t ${JSON.stringify(sessionName)} ${JSON.stringify(launchFile)} Enter`)
+
+  // Attach — this takes over the terminal
+  spawnSync('tmux', ['attach-session', '-t', sessionName], { stdio: 'inherit' })
+}

package/lib/commands/spawn.js

@@ -1,28 +1,42 @@
 import chalk from 'chalk'
 import { spawnSync } from 'child_process'
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { tmpdir, homedir } from 'os'
-import { readConfig } from '../utils/config.js'
+import { readConfig, CONFIG_PATH } from '../utils/config.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SCRIPTS_DIR = join(__dirname, '..', '..', 'scripts')
 const INBOX_DIR = join(homedir(), '.shellmates', 'inbox')
 
 export async function spawn(options) {
+  if (!existsSync(CONFIG_PATH)) {
+    console.log(chalk.yellow('\n  ~ Not initialized yet.'))
+    console.log('  Run ' + chalk.bold('shellmates init') + ' first.\n')
+    process.exit(1)
+  }
+
   const config = readConfig()
 
-  const agent = options.agent || config.default_agent
-  const session = options.session || `shellmates-${Date.now()}`
+  // Resolve agents: --agent flag (single) overrides config; config may have array
+  let agents
+  if (options.agent) {
+    agents = [options.agent]
+  } else {
+    // Support both old default_agent and new default_agents
+    agents = config.default_agents
+      || (config.default_agent ? [config.default_agent] : ['gemini'])
+  }
+
+  const ts = Date.now()
   const project = options.project || process.cwd()
   const noPing = options.noPing || false
 
-  // Resolve task content
+  // Resolve task file
   let taskFile = options.taskFile
   if (!taskFile && options.task) {
-    // Inline task string → write to temp file
-    const tmp = join(tmpdir(), `shellmates-task-${Date.now()}.txt`)
+    const tmp = join(tmpdir(), `shellmates-task-${ts}.txt`)
     writeFileSync(tmp, options.task)
     taskFile = tmp
   }
@@ -32,67 +46,94 @@ export async function spawn(options) {
     process.exit(1)
   }
 
+  const parallel = agents.length > 1
+
   console.log('')
   console.log(chalk.bold('  Shellmates — Spawning'))
   console.log(chalk.dim('  ─────────────────────────────────────'))
-  console.log(chalk.dim('  Agent:   ') + chalk.bold(agent))
-  console.log(chalk.dim('  Session: ') + chalk.bold(session))
-  console.log(chalk.dim('  Mode:    ') + chalk.bold(config.permission_mode))
+  if (parallel) {
+    console.log(chalk.dim('  Agents:  ') + chalk.bold(agents.join(' + ')))
+    console.log(chalk.dim('  Mode:    parallel'))
+  } else {
+    console.log(chalk.dim('  Agent:   ') + chalk.bold(agents[0]))
+  }
+  console.log(chalk.dim('  Perms:   ') + chalk.bold(config.permission_mode))
   console.log('')
 
   const spawnScript = join(SCRIPTS_DIR, 'spawn-team.sh')
-  const args = [
-    '--task-file', taskFile,
-    '--project', project,
-    '--session', session,
-    '--agent', agent,
-  ]
-  if (noPing) args.push('--no-ping')
-
-  const result = spawnSync('bash', [spawnScript, ...args], { stdio: 'inherit' })
-
-  if (result.status !== 0) {
-    console.error(chalk.red('\n  ✗ Spawn failed'))
-    process.exit(result.status || 1)
+  const sessions = []
+
+  for (const agent of agents) {
+    const session = options.session
+      ? (agents.length > 1 ? `${options.session}-${agent}` : options.session)
+      : `shellmates-${agent}-${ts}`
+
+    const args = [
+      '--task-file', taskFile,
+      '--project', project,
+      '--session', session,
+      '--agent', agent,
+    ]
+    if (noPing) args.push('--no-ping')
+
+    const result = spawnSync('bash', [spawnScript, ...args], { stdio: 'inherit' })
+
+    if (result.status !== 0) {
+      console.error(chalk.red(`\n  ✗ Spawn failed for ${agent}`))
+      process.exit(result.status || 1)
+    }
+
+    sessions.push(session)
+  }
+
+  if (parallel) {
+    console.log('')
+    console.log(chalk.dim('  Sessions:'))
+    for (const s of sessions) {
+      console.log(chalk.dim('    • ') + s)
+    }
   }
 
-  // If --watch, tail the inbox until the job file appears
   if (options.watch) {
-    await watchInbox(session)
+    await watchInbox(sessions)
   }
 }
 
-async function watchInbox(session) {
+async function watchInbox(sessions) {
   const { readdir } = await import('fs/promises')
   console.log('')
-  console.log(chalk.dim('  Watching for result...  (Ctrl+C to stop)'))
+  console.log(chalk.dim('  Watching for results...  (Ctrl+C to stop)'))
 
   const before = new Set(existsSync(INBOX_DIR)
     ? (await readdir(INBOX_DIR)).filter(f => f.endsWith('.txt'))
     : [])
 
+  const remaining = new Set(sessions)
   let elapsed = 0
   const timeout = 300
-  while (elapsed < timeout) {
+
+  while (elapsed < timeout && remaining.size > 0) {
     await new Promise(r => setTimeout(r, 2000))
     elapsed += 2
     if (!existsSync(INBOX_DIR)) continue
     const after = (await readdir(INBOX_DIR)).filter(f => f.endsWith('.txt'))
     const newFiles = after.filter(f => !before.has(f))
-    if (newFiles.length > 0) {
-      for (const f of newFiles) {
-        const content = readFileSync(join(INBOX_DIR, f), 'utf8')
-        console.log('')
-        console.log(chalk.green('  ✓ Result received') + chalk.dim(` (${f})`))
-        console.log('')
-        for (const line of content.trim().split('\n')) {
-          console.log('  ' + chalk.dim(line.split(':')[0] + ':') + ' ' + line.split(':').slice(1).join(':').trim())
-        }
-        console.log('')
+    for (const f of newFiles) {
+      const content = readFileSync(join(INBOX_DIR, f), 'utf8')
+      const matchingSession = sessions.find(s => f.includes(s))
+      console.log('')
+      console.log(chalk.green('  ✓ Result received') + chalk.dim(` (${matchingSession || f})`))
+      console.log('')
+      for (const line of content.trim().split('\n')) {
+        const [key, ...rest] = line.split(':')
+        console.log('  ' + chalk.dim(key + ':') + ' ' + rest.join(':').trim())
       }
-      return
+      if (matchingSession) remaining.delete(matchingSession)
+      before.add(f)
     }
   }
 
-  console.log(chalk.yellow('\n  ~ Timed out waiting for result'))
+  if (remaining.size > 0) {
+    console.log(chalk.yellow('\n  ~ Timed out waiting for: ' + [...remaining].join(', ')))
+  }
 }

package/lib/commands/update.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk'
+import { spawnSync } from 'child_process'
+
+export async function update() {
+  console.log('')
+  console.log(chalk.bold('  Shellmates — Update'))
+  console.log(chalk.dim('  ─────────────────────────────────────'))
+  console.log('')
+  console.log(chalk.dim('  Running: npm install -g shellmates@latest'))
+  console.log('')
+
+  const result = spawnSync('npm', ['install', '-g', 'shellmates@latest'], {
+    stdio: 'inherit',
+    shell: true,
+  })
+
+  if (result.status === 0) {
+    console.log('')
+    console.log(chalk.green('  ✓') + ' Updated. Run ' + chalk.bold('shellmates') + ' to see the new version.')
+    console.log('')
+  } else {
+    console.log('')
+    console.log(chalk.red('  ✗') + ' Update failed.')
+    console.log(chalk.dim('    Try manually: npm install -g shellmates@latest'))
+    console.log('')
+    process.exit(1)
+  }
+}

package/lib/utils/agents.js

@@ -0,0 +1,88 @@
+import { execSync, spawnSync } from 'child_process'
+import chalk from 'chalk'
+
+export const AGENTS = {
+  gemini: {
+    label: 'Gemini CLI',
+    bin: 'gemini',
+    pkg: '@google/gemini-cli',
+    hint: 'google/gemini-cli',
+  },
+  codex: {
+    label: 'Codex CLI',
+    bin: 'codex',
+    pkg: '@openai/codex',
+    hint: 'openai/codex',
+  },
+  claude: {
+    label: 'Claude Code',
+    bin: 'claude',
+    pkg: '@anthropic-ai/claude-code',
+    hint: 'anthropic-ai/claude-code',
+  },
+}
+
+/** Returns { gemini: true, codex: false, claude: true } */
+export function detectAgents() {
+  const results = {}
+  for (const [key, agent] of Object.entries(AGENTS)) {
+    try {
+      execSync(`which ${agent.bin}`, { stdio: 'ignore' })
+      results[key] = true
+    } catch {
+      results[key] = false
+    }
+  }
+  return results
+}
+
+/** Print detection results and offer to install missing agents. */
+export async function checkAndInstallAgents() {
+  const { default: inquirer } = await import('inquirer')
+  const detected = detectAgents()
+  const missing = Object.entries(detected).filter(([, ok]) => !ok).map(([k]) => k)
+
+  console.log('  Checking agents...')
+  for (const [key, ok] of Object.entries(detected)) {
+    const a = AGENTS[key]
+    if (ok) {
+      console.log(chalk.green('  ✓') + ` ${a.label.padEnd(14)} ${chalk.dim(a.hint)}`)
+    } else {
+      console.log(chalk.red('  ✗') + ` ${a.label.padEnd(14)} ${chalk.dim('not found')}`)
+    }
+  }
+
+  if (missing.length === 0) return
+
+  console.log('')
+  const { toInstall } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'toInstall',
+      message: 'Install missing agents?',
+      choices: missing.map(k => ({
+        name: `${AGENTS[k].label}  ${chalk.dim(AGENTS[k].hint)}`,
+        value: k,
+        checked: true,
+      })),
+      prefix: ' ',
+    },
+  ])
+
+  if (toInstall.length === 0) return
+
+  console.log('')
+  for (const key of toInstall) {
+    const a = AGENTS[key]
+    console.log(chalk.dim(`  Installing ${a.label}...`))
+    const result = spawnSync('npm', ['install', '-g', `${a.pkg}@latest`], {
+      stdio: 'inherit',
+      shell: true,
+    })
+    if (result.status === 0) {
+      console.log(chalk.green('  ✓') + ` ${a.label} installed`)
+    } else {
+      console.log(chalk.yellow('  ~') + ` ${a.label} install failed — try: ${chalk.dim(`npm install -g ${a.pkg}@latest`)}`)
+    }
+  }
+}

package/lib/utils/update-check.js

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+const CACHE_PATH = join(homedir(), '.shellmates', 'update-cache.json')
+const TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+export async function checkUpdate(currentVersion) {
+  // Try cache first
+  let latestVersion = null
+  if (existsSync(CACHE_PATH)) {
+    try {
+      const cache = JSON.parse(readFileSync(CACHE_PATH, 'utf8'))
+      if (Date.now() - cache.checkedAt < TTL_MS) {
+        latestVersion = cache.latest
+      }
+    } catch {}
+  }
+
+  if (!latestVersion) {
+    try {
+      const res = await fetch('https://registry.npmjs.org/shellmates/latest', {
+        signal: AbortSignal.timeout(3000),
+      })
+      const data = await res.json()
+      latestVersion = data.version
+      try {
+        mkdirSync(join(homedir(), '.shellmates'), { recursive: true })
+        writeFileSync(CACHE_PATH, JSON.stringify({ latest: latestVersion, checkedAt: Date.now() }))
+      } catch {}
+    } catch {
+      return null // network error or timeout — silent
+    }
+  }
+
+  if (!latestVersion || !isNewer(latestVersion, currentVersion)) return null
+  return { current: currentVersion, latest: latestVersion }
+}
+
+function isNewer(a, b) {
+  const p = v => v.replace(/[^0-9.]/g, '').split('.').map(Number)
+  const [aM, am, ap] = p(a)
+  const [bM, bm, bp] = p(b)
+  if (aM !== bM) return aM > bM
+  if (am !== bm) return am > bm
+  return ap > bp
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellmates",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Seamless tmux multi-agent orchestration for Claude, Gemini, and Codex",
   "keywords": [
     "tmux",
@@ -14,7 +14,7 @@
   "homepage": "https://github.com/rs07-git/shellmates",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rs07-git/shellmates.git"
+    "url": "git+https://github.com/rs07-git/shellmates.git"
   },
   "license": "MIT",
   "type": "module",