cru-teams 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+<p align="center"><img src="assets/logo.svg" width="128"/></p>
+
+# ◫ cru
+
+Layout for [Claude Code agent teams](https://code.claude.com/docs/en/agent-teams), fixed.
+
+Agent teams let multiple Claude Code instances work together in parallel — cru handles the terminal layout so you don't have to.
+
+```
+╭──────────────────┬────────────────┬────────────────╮
+│                  │                │                │
+│                  │  ⚡ worker-1    │  ⚡ worker-2    │
+│                  │                │                │
+│       lead       ├────────────────┼────────────────┤
+│                  │                │                │
+│                  │  ⚡ worker-3    │  ⚡ worker-4    │
+│                  │                │                │
+╰──────────────────┴────────────────┴────────────────╯
+```
+
+![demo](assets/demo.gif)
+
+## Terminal setup
+
+- **Already using tmux?** You're good.
+- **iTerm2?** Use [`tmux -CC`](https://iterm2.com/documentation-tmux-integration.html) for native pane integration.
+- **Ghostty?** Workers still run in tmux (that's how Claude Code spawns agents), but cru mirrors them into native Ghostty splits via [AppleScript](https://ghostty.org/docs/features/applescript) — so you get Ghostty's UI instead of working inside tmux yourself. Requires Ghostty v1.3.0+.
+
+## Install
+
+```bash
+npm install -g cru-teams
+```
+```bash
+pnpm add -g cru-teams
+```
+```bash
+bun add -g cru-teams
+```
+
+## Quick start
+
+1. Set up cru in your project:
+
+```bash
+cru init
+```
+
+2. In Claude Code, spawn a team:
+
+```
+/cru split the auth module into subtasks and parallelize across workers
+```
+
+That's it — cru creates the panes, applies the grid layout, and your workers are ready to go.
+
+## Use cases
+
+**[Parallel feature work](https://code.claude.com/docs/en/agent-teams#when-to-use-agent-teams)** — split subtasks across workers, merge when done
+
+  ```
+  /cru break down the checkout flow into vertical slices, one worker per slice
+  ```
+**[Review crew](https://code.claude.com/docs/en/agent-teams#run-a-parallel-code-review)** — workers build, one reviews
+
+  ```
+  /cru 3 review PR #142 — one on security, one on performance, one on test coverage
+  ```
+**[Competing hypotheses](https://code.claude.com/docs/en/agent-teams#investigate-with-competing-hypotheses)** — debug faster with multiple theories at once
+
+  ```
+  /cru users report the app crashes on login — each worker investigates a different theory
+  ```
+
+**[Research spike](https://code.claude.com/docs/en/agent-teams#start-with-research-and-review)** — explore different approaches simultaneously
+  ```
+  /cru 3 evaluate auth libraries — one on passport, one on lucia, one on arctic
+  ```
+
+## Documentation
+
+- [CLI reference](CLI.md) — all commands, flags, and examples
+- [Configuration](CONFIG.md) — layout options, config files, resolution order
+- [Testing](TESTING.md) — test structure and how to run tests

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cru-teams",
+  "version": "1.0.0",
+  "description": "◫ Manage terminal layouts for Claude Code agent teams",
+  "type": "module",
+  "bin": {
+    "cru": "./src/cli.ts"
+  },
+  "files": [
+    "src/",
+    "skills/"
+  ],
+  "scripts": {
+    "dev": "bun src/cli.ts",
+    "test": "bun test tests/unit/",
+    "test:e2e": "bun test tests/e2e/ --timeout 120000",
+    "publish": "npm publish --access public"
+  },
+  "keywords": [
+    "claude-code",
+    "cru",
+    "tmux",
+    "layout"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "incur": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@types/node": "^25.3.5"
+  }
+}

package/skills/cru/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: cru
+description: Spawn an agent team with workers arranged in a grid layout. Use when the user wants to create a team of agents.
+argument-hint: "<task description>"
+disable-model-invocation: true
+---
+
+# Spawn Agent Team
+
+## Arguments
+
+Parse `$ARGUMENTS` as a single string:
+
+- If the **first word is a number**, use it as the worker count and the rest as the task description.
+- If the **first word is NOT a number**, use the entire string as the task description and decide the worker count yourself based on the task (typically 2–5).
+
+## Steps
+
+1. **Determine worker count and task** from `$ARGUMENTS` using the rules above.
+
+2. **Create the team** using TeamCreate.
+
+3. **Spawn workers** using the Agent tool. For each worker (worker-1 through worker-N):
+   - Set `team_name` to the team name from step 2
+   - Set `name` to "worker-1", "worker-2", etc.
+   - Set `subagent_type` to "general-purpose"
+   - Set `run_in_background` to true
+   - Give each worker its specific task slice in the `prompt`, plus:
+     - Context about what other workers are doing
+     - An instruction to message teammates to share findings and discuss
+
+   **IMPORTANT:** Spawn all workers AND apply the grid layout in a **single message** — include all Agent calls AND the Bash call for `cru panes grid` together. This ensures the grid command starts polling immediately while workers are still launching.
+
+4. **Apply grid layout** (in the same message as step 3):
+   ```bash
+   cru panes grid <team-name> --expect <worker-count>
+   ```
+   This polls for worker panes (up to 30s) and arranges them in a grid. In Ghostty, it automatically mirrors tmux panes into native splits.
+
+   If the grid command fails (e.g., not in a tmux session), that's OK — workers still run as background agents with the team bar visible. Tell the user they can start a tmux session for the grid layout.
+
+5. **Report** the team is ready. Tell the user:
+   - What each worker is focused on
+   - `cru panes close <team-name>` to shut down when done
+
+## Shutdown
+
+1. **Send shutdown requests first** — use `SendMessage` with `type: "shutdown_request"` to each worker. Wait for approvals (or idle notifications).
+2. **Then close panes** — `cru panes close <team-name>`
+3. **Then delete team** — `TeamDelete`
+
+Closing panes before agents approve kills them mid-process, which causes `TeamDelete` to see "active" members and refuse cleanup.
+
+Team data (logs, messages) is preserved after close — reviewable via `cru logs <team>`. Use `cru clean` to remove old teams.

package/src/cli.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+import { Cli } from 'incur'
+import { preflight } from '@/lib/preflight'
+
+// Entity commands
+import { teams } from '@/commands/teams'
+import { panes } from '@/commands/panes'
+import { tasks } from '@/commands/tasks'
+
+// Layout
+import { config } from '@/commands/config'
+
+// Meta
+import { init } from '@/commands/init'
+import { doctor } from '@/commands/doctor'
+import { logs } from '@/commands/logs'
+import { clean } from '@/commands/clean'
+
+// Commands that require specific preflight checks
+const PREFLIGHT: Record<string, string[]> = {
+  panes: ['pane-session'],
+}
+
+Cli.create('cru', {
+  description: '◫ Manage pane layouts for Claude Code agent teams',
+  version: '1.0.0',
+})
+  .use(async (c, next) => {
+    const checks = PREFLIGHT[c.command]
+    if (checks) {
+      const result = preflight(...checks)
+      if (!result.ok) {
+        const e = result.errors[0]
+        return c.error({ code: e.check.toUpperCase(), message: e.message })
+      }
+    }
+    await next()
+  })
+  // Entity commands
+  .command('teams', teams)
+  .command('panes', panes)
+  .command('tasks', tasks)
+  // Config & meta
+  .command('config', config)
+  .command('init', init)
+  .command('doctor', doctor)
+  .command('logs', logs)
+  .command('clean', clean)
+  .serve()

package/src/commands/clean.ts

@@ -0,0 +1,78 @@
+import { readdirSync, rmSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { z } from 'incur'
+import { isTeamAlive } from '@/lib/panes'
+import { teamsDir } from '@/lib/paths'
+
+export const clean = {
+  description: 'Remove old team data from ~/.claude/teams',
+  options: z.object({
+    days: z.coerce.number().default(7).describe('Remove teams older than N days'),
+    all: z.boolean().default(false).describe('Remove all teams'),
+    'dry-run': z.boolean().default(false).describe('Show what would be removed without deleting'),
+  }),
+  run(c) {
+    const dir = teamsDir()
+    let teams: string[]
+    try {
+      teams = readdirSync(dir).filter((d) => {
+        try {
+          statSync(join(dir, d, 'config.json'))
+          return true
+        } catch {
+          return false
+        }
+      })
+    } catch {
+      return { removed: 0, teams: [] }
+    }
+
+    const now = Date.now()
+    const maxAge = c.options.days * 24 * 60 * 60 * 1000
+    const toRemove: Array<{ name: string; age: string }> = []
+
+    for (const name of teams) {
+      const configPath = join(dir, name, 'config.json')
+      try {
+        const stat = statSync(configPath)
+        const age = now - stat.mtimeMs
+        const dead = !isTeamAlive(name)
+
+        if (c.options.all || age > maxAge || dead) {
+          const days = Math.floor(age / (24 * 60 * 60 * 1000))
+          const reason = dead ? 'dead' : days === 0 ? 'today' : `${days}d ago`
+          toRemove.push({ name, age: reason })
+        }
+      } catch {}
+    }
+
+    if (toRemove.length === 0) {
+      if (!c.agent) console.log('Nothing to clean')
+      return { removed: 0, teams: [] }
+    }
+
+    if (c.options['dry-run']) {
+      if (!c.agent) {
+        console.log(`Would remove ${toRemove.length} teams:\n`)
+        for (const t of toRemove) console.log(`  ${t.name}  ${t.age}`)
+      }
+      return { 'dry-run': true, would_remove: toRemove.length, teams: toRemove }
+    }
+
+    const tasksBaseDir = join(homedir(), '.claude', 'tasks')
+    for (const t of toRemove) {
+      rmSync(join(dir, t.name), { recursive: true, force: true })
+      // Also clean up tasks for this team
+      try {
+        rmSync(join(tasksBaseDir, t.name), { recursive: true, force: true })
+      } catch {}
+    }
+
+    if (!c.agent) {
+      console.log(`Removed ${toRemove.length} teams`)
+    }
+
+    return { removed: toRemove.length, teams: toRemove }
+  },
+}

package/src/commands/config.ts

@@ -0,0 +1,11 @@
+import { existsSync } from 'node:fs'
+import { configPaths, loadConfig } from '@/lib/config'
+
+export const config = {
+  description: 'Show resolved config (merged defaults + overrides)',
+  run() {
+    const conf = loadConfig()
+    const loaded = configPaths().find((p) => existsSync(p)) || 'defaults'
+    return { source: loaded, config: conf }
+  },
+}

package/src/commands/doctor.ts

@@ -0,0 +1,82 @@
+import { z } from 'incur'
+import { hasBinary, getVersion, inTmux, inGhostty, detectTerminal } from '@/lib/env'
+
+export const doctor = {
+  description: 'Check environment requirements for cru',
+  args: z.object({}),
+  options: z.object({
+    json: z.boolean().default(false).describe('Output as JSON'),
+  }),
+  run(c) {
+    const terminal = detectTerminal()
+    const tmuxCmd = terminal === 'iterm2' ? 'tmux -CC' : 'tmux'
+
+    const checks: Array<{
+      name: string
+      status: 'ok' | 'fail'
+      detail: string
+      fix?: string
+    }> = []
+
+    const tmuxPath = hasBinary('tmux')
+    if (!tmuxPath) {
+      checks.push({
+        name: 'tmux',
+        status: 'fail',
+        detail: 'not installed',
+        fix: process.platform === 'darwin' ? 'brew install tmux' : 'sudo apt install tmux',
+      })
+    } else {
+      checks.push({ name: 'tmux', status: 'ok', detail: getVersion('tmux -V') || 'installed' })
+    }
+
+    if (tmuxPath && !inTmux() && !inGhostty()) {
+      checks.push({ name: 'tmux-session', status: 'fail', detail: 'not inside a tmux session', fix: tmuxCmd })
+    } else if (tmuxPath && inTmux()) {
+      checks.push({ name: 'tmux-session', status: 'ok', detail: 'active' })
+    }
+
+    const claudePath = hasBinary('claude')
+    if (!claudePath) {
+      checks.push({ name: 'claude', status: 'fail', detail: 'not installed', fix: 'npm install -g @anthropic-ai/claude-code' })
+    } else {
+      checks.push({ name: 'claude', status: 'ok', detail: getVersion('claude --version') || 'installed' })
+    }
+
+    // Ghostty native pane support (AppleScript)
+    if (terminal === 'ghostty') {
+      if (process.platform !== 'darwin') {
+        checks.push({ name: 'ghostty', status: 'fail', detail: 'AppleScript only available on macOS' })
+      } else {
+        try {
+          const { ghosttyVersion, isGhosttyScriptable } = require('@/lib/ghostty')
+          if (isGhosttyScriptable()) {
+            const ver = ghosttyVersion() || 'unknown'
+            checks.push({ name: 'ghostty', status: 'ok', detail: `v${ver} (AppleScript enabled)` })
+          } else {
+            checks.push({ name: 'ghostty', status: 'fail', detail: 'AppleScript not responding', fix: 'Set macos-applescript = true in Ghostty config' })
+          }
+        } catch {
+          checks.push({ name: 'ghostty', status: 'fail', detail: 'cannot connect via AppleScript' })
+        }
+      }
+
+      if (inGhostty()) {
+        checks.push({ name: 'pane-backend', status: 'ok', detail: 'ghostty (native AppleScript)' })
+      } else if (inTmux()) {
+        checks.push({ name: 'pane-backend', status: 'ok', detail: 'tmux (inside Ghostty)' })
+      }
+    }
+
+    const bunPath = hasBinary('bun')
+    if (!bunPath) {
+      checks.push({ name: 'bun', status: 'fail', detail: 'not installed', fix: 'curl -fsSL https://bun.sh/install | bash' })
+    } else {
+      checks.push({ name: 'bun', status: 'ok', detail: `v${getVersion('bun --version')}` })
+    }
+
+    const ok = checks.every((ch) => ch.status === 'ok')
+
+    return { ok, terminal, tmuxCmd, checks }
+  },
+}

package/src/commands/init.ts

@@ -0,0 +1,35 @@
+import { z } from 'incur'
+import { existsSync, mkdirSync, cpSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { CONFIG_NAME, DEFAULTS, writeConfig } from '@/lib/config'
+
+export const init = {
+  description: 'Set up cru in the current project',
+  options: z.object({
+    force: z.boolean().default(false).describe('Overwrite existing files'),
+  }),
+  run(c) {
+    const cwd = process.cwd()
+    const files: Record<string, string> = {}
+
+    // 1. Config file
+    const configPath = join(cwd, CONFIG_NAME)
+    if (!existsSync(configPath) || c.options.force) {
+      writeConfig(configPath, DEFAULTS)
+      files[CONFIG_NAME] = 'created'
+    } else {
+      files[CONFIG_NAME] = 'exists'
+    }
+
+    // 2. Install skill to .claude/skills/
+    const pkgRoot = dirname(dirname(import.meta.dirname))
+    const skillSrc = join(pkgRoot, 'skills', 'cru')
+    const skillDest = join(cwd, '.claude', 'skills', 'cru')
+
+    mkdirSync(join(cwd, '.claude', 'skills'), { recursive: true })
+    cpSync(skillSrc, skillDest, { recursive: true })
+    files['.claude/skills/cru/'] = existsSync(join(skillDest, 'SKILL.md')) ? 'updated' : 'installed'
+
+    return { files, tip: 'Use /cru in Claude Code to spawn a team.' }
+  },
+}