@brimveyn/aimux 1.18.1 → 1.18.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.18.1",
+  "version": "1.18.3",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/src/cli/index.ts

@@ -3,7 +3,7 @@ import type { CliContext } from './context'
 
 import { connectToDaemon, DaemonUnreachableError } from './client/bootstrap'
 import { resolveWorkspace } from './client/workspace-resolver'
-import { CliUsageError, parseArgs } from './flags'
+import { type ArgSpec, CliUsageError, type FlagSpec, parseArgs, SHARED_FLAGS } from './flags'
 import {
   EXIT_DAEMON_UNREACHABLE,
   EXIT_OK,
@@ -12,24 +12,148 @@ import {
   writeError,
   writeJson,
 } from './output'
-import { COMMANDS, resolveCommand } from './registry'
+import { type CliCommand, COMMANDS, resolveCommand } from './registry'
+
+const EXIT_CODES_BLOCK = [
+  'Exit codes:',
+  '  0    success',
+  '  2    usage error (bad flags, unknown command, missing argument)',
+  '  3    runtime error (server replied with error, command failed)',
+  '  4    daemon unreachable (socket missing and autostart failed)',
+  '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
+].join('\n')
+
+const OUTPUT_CONTRACT_BLOCK = [
+  'Output contract:',
+  '  stdout  one JSON object per command (NDJSON for `tab tail`, `tab wait`)',
+  '  stderr  human-readable error lines, prefixed with `aimux:`',
+].join('\n')
+
+function groupByCommand(commands: readonly CliCommand[]): Map<string, CliCommand[]> {
+  const byGroup = new Map<string, CliCommand[]>()
+  for (const command of commands) {
+    const existing = byGroup.get(command.group) ?? []
+    existing.push(command)
+    byGroup.set(command.group, existing)
+  }
+  return byGroup
+}
+
+function isSharedFlag(name: string): boolean {
+  return SHARED_FLAGS.some((f) => f.name === name)
+}
+
+function formatArgs(args: readonly ArgSpec[]): string {
+  if (args.length === 0) return ''
+  return args.map((a) => (a.required === true ? `<${a.name}>` : `[${a.name}]`)).join(' ')
+}
+
+function flagValueHint(flag: FlagSpec): string {
+  if (flag.kind === 'boolean') return ''
+  if (flag.kind === 'number') return ' <n>'
+  return ` <${flag.name}>`
+}
+
+function formatFlagLine(flag: FlagSpec): string {
+  const head = `  --${flag.name}${flagValueHint(flag)}`.padEnd(32)
+  return `${head}${flag.description ?? ''}`
+}
 
 function printHelp(): void {
   process.stdout.write(
-    'aimux CLI control plane\n\nUsage:\n  aimux <group> <verb> [flags] [args]\n\n'
+    [
+      'aimux CLI control plane — drive workspaces, worktrees, and tabs from scripts.',
+      '',
+      'Usage:',
+      '  aimux <group> <verb> [flags] [args]',
+      '  aimux <group> --help                        List verbs in a group',
+      '  aimux <group> <verb> --help                 Show flags/args for a verb',
+      '',
+      'Groups:',
+      '',
+    ].join('\n')
   )
-  const byGroup = new Map<string, typeof COMMANDS>()
-  for (const command of COMMANDS) {
-    const existing = byGroup.get(command.group) ?? []
-    byGroup.set(command.group, [...existing, command] as typeof COMMANDS)
-  }
+
+  const byGroup = groupByCommand(COMMANDS)
   for (const [group, commands] of byGroup) {
     process.stdout.write(`  ${group}\n`)
     for (const command of commands) {
-      process.stdout.write(`    aimux ${group} ${command.verb.padEnd(10)} ${command.summary}\n`)
+      const args = formatArgs(command.args)
+      const signature = `aimux ${group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+      process.stdout.write(`    ${signature.padEnd(46)} ${command.summary}\n`)
     }
     process.stdout.write('\n')
   }
+
+  process.stdout.write(
+    [
+      'Shared flags (accepted by every command):',
+      ...SHARED_FLAGS.map(formatFlagLine),
+      '',
+      OUTPUT_CONTRACT_BLOCK,
+      '',
+      EXIT_CODES_BLOCK,
+      '',
+      'Env:',
+      '  AIMUX_PROFILE                  Runtime profile (state dir, socket paths); --profile overrides.',
+      '',
+      'Agent recipes:',
+      '  # spawn Claude in a new tab, wait until it idles, snapshot the screen',
+      '  TAB=$(aimux tab create --assistant claude --title fixup | jq -r .tabId)',
+      '  aimux tab send "$TAB" "explain this repo" --enter',
+      '  aimux tab wait "$TAB" --status idle --timeout 60000',
+      '  aimux tab snapshot "$TAB" --tail 40 --format text',
+      '',
+      '  # stream renders as NDJSON (one event per line)',
+      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
+      '',
+    ].join('\n')
+  )
+}
+
+function printGroupHelp(group: string): void {
+  const commands = COMMANDS.filter((c) => c.group === group)
+  if (commands.length === 0) {
+    printHelp()
+    return
+  }
+  process.stdout.write(
+    [
+      `aimux ${group} — ${commands.length} verb${commands.length === 1 ? '' : 's'}`,
+      '',
+      'Usage:',
+      `  aimux ${group} <verb> [flags] [args]`,
+      `  aimux ${group} <verb> --help    Show flags/args for a verb`,
+      '',
+      'Verbs:',
+      '',
+    ].join('\n')
+  )
+  for (const command of commands) {
+    const args = formatArgs(command.args)
+    const signature = `aimux ${group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+    process.stdout.write(`  ${signature.padEnd(46)} ${command.summary}\n`)
+  }
+  process.stdout.write('\n')
+}
+
+function printCommandHelp(command: CliCommand): void {
+  const args = formatArgs(command.args)
+  const signature = `aimux ${command.group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+  process.stdout.write([signature, '', `  ${command.summary}`, '', 'Flags:', ''].join('\n'))
+  const own = command.flags.filter((f) => !isSharedFlag(f.name))
+  if (own.length === 0) {
+    process.stdout.write('  (this command takes only the shared flags)\n')
+  } else {
+    for (const flag of own) process.stdout.write(`${formatFlagLine(flag)}\n`)
+  }
+  process.stdout.write('\nShared flags:\n')
+  for (const flag of SHARED_FLAGS) process.stdout.write(`${formatFlagLine(flag)}\n`)
+  process.stdout.write(`\n${OUTPUT_CONTRACT_BLOCK}\n\n${EXIT_CODES_BLOCK}\n`)
+}
+
+function argvRequestsHelp(argv: readonly string[]): boolean {
+  return argv.includes('--help') || argv.includes('-h')
 }
 
 export async function runCli(argv: readonly string[]): Promise<number> {
@@ -40,6 +164,20 @@ export async function runCli(argv: readonly string[]): Promise<number> {
 
   const group = argv[0] ?? ''
   const verb = argv[1] ?? ''
+
+  // `aimux <group> --help` (or bare `aimux <group>`) — group-scoped help. Print
+  // the verb list without erroring on the missing verb, so agents can drill
+  // down step by step.
+  if (verb === '' || verb === '--help' || verb === '-h') {
+    if (COMMANDS.some((c) => c.group === group)) {
+      printGroupHelp(group)
+      return EXIT_OK
+    }
+    writeError(`unknown group: ${group}`)
+    printHelp()
+    return EXIT_USAGE
+  }
+
   const command = resolveCommand(group, verb)
   if (!command) {
     writeError(`unknown command: ${group} ${verb}`)
@@ -47,6 +185,13 @@ export async function runCli(argv: readonly string[]): Promise<number> {
     return EXIT_USAGE
   }
 
+  // `aimux <group> <verb> --help` — verb-scoped help. Handle BEFORE parseArgs
+  // so verbs that don't declare a `--help` flag don't reject it as unknown.
+  if (argvRequestsHelp(argv.slice(2))) {
+    printCommandHelp(command)
+    return EXIT_OK
+  }
+
   let parsed
   try {
     parsed = parseArgs(argv.slice(2), command.flags, command.args)

package/src/index.tsx

@@ -60,9 +60,78 @@ if (command === 'terminal-manager') {
   await runTerminalManager()
 }
 
-if (command === '--help' || command === '-h') {
+if (command === '--help' || command === '-h' || command === 'help') {
   process.stdout.write(
-    'aimux -- terminal multiplexer for AI CLIs\n\nUsage:\n  aimux                           Start aimux\n  aimux update                    Update to latest version\n  aimux doctor                    Diagnose setup issues\n  aimux restart-daemon            Restart IPC daemon\n  aimux restart-terminal-manager  Restart terminal-manager (kills live workspaces)\n\n'
+    [
+      'aimux — terminal multiplexer for AI CLIs',
+      '',
+      'Two surfaces:',
+      '  • Interactive TUI (no args): drive assistants side-by-side in one window.',
+      '  • CLI control plane (`aimux <group> <verb>`): script-friendly, JSON output,',
+      '    designed to be driven by another agent or a shell pipeline.',
+      '',
+      'Interactive',
+      '  aimux                             Start the TUI in the current profile',
+      '',
+      'CLI control plane (JSON on stdout, human-readable errors on stderr)',
+      '  aimux tab       list | create | send | focus | close | snapshot | tail | wait',
+      '  aimux workspace list | show | create | switch | close',
+      '  aimux worktree  list | create | remove',
+      '',
+      '  aimux <group> --help              List verbs in that group',
+      '  aimux <group> <verb> --help       Show flags, args, and exit codes',
+      '',
+      'Common CLI verbs at a glance',
+      '  aimux tab list                                     Enumerate tabs (+ activeTabId)',
+      '  aimux tab create --assistant <id> [--title …]      Spawn claude / codex / opencode / terminal / …',
+      '  aimux tab send <tabId> [text] [--enter|--keys|--stdin]  Type, chord, or paste into a tab',
+      '  aimux tab focus <tabId>                            Bring a tab to the foreground',
+      '  aimux tab close <tabId>                            Terminate a tab',
+      '  aimux tab snapshot <tabId> [--tail N] [--format …] Capture the screen (json | text)',
+      '  aimux tab tail <tabId> [--follow-status] […]       NDJSON stream of renders / status',
+      '  aimux tab wait <tabId> --status <idle|working|waiting-input>  Block on an activity state',
+      '  aimux workspace show                               Dump the active workspace + worktrees',
+      '  aimux workspace create <name> [--project P] [--switch [--wait]]',
+      '  aimux workspace switch <ws> [--wait --timeout N]   Move the running UI to another workspace',
+      '  aimux worktree create --name <n> [--branch B --base R]',
+      '  aimux worktree remove <id|path> [--force]',
+      '',
+      'Shared flags (accepted by every CLI verb)',
+      '  --workspace <id|name>             Target a specific workspace (default: active)',
+      '  --profile <name>                  Runtime profile (also settable via AIMUX_PROFILE)',
+      '  --json                            Reserved; JSON is always on',
+      '',
+      'Maintenance',
+      '  aimux update                      Update aimux to the latest published version',
+      '  aimux doctor                      Diagnose setup (paths, sockets, PTY, integrations)',
+      '  aimux restart-daemon              Restart the IPC daemon (keeps live workspaces)',
+      '  aimux restart-terminal-manager    Restart terminal-manager (kills live workspaces)',
+      '  aimux --version                   Print the installed version',
+      '',
+      'Exit codes',
+      '  0    success',
+      '  2    usage error (bad flags, unknown command, missing argument)',
+      '  3    runtime error (server replied with error, command failed)',
+      '  4    daemon unreachable (socket missing and autostart failed)',
+      '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
+      '',
+      'Env',
+      '  AIMUX_PROFILE                     Runtime profile (state dir, socket paths)',
+      '',
+      'Recipes for agents',
+      '  # spawn Claude, wait for idle, dump the last 40 non-blank lines',
+      '  TAB=$(aimux tab create --assistant claude --title fixup | jq -r .tabId)',
+      '  aimux tab send "$TAB" "explain this repo" --enter',
+      '  aimux tab wait "$TAB" --status idle --timeout 60000',
+      '  aimux tab snapshot "$TAB" --tail 40 --format text',
+      '',
+      '  # send a control chord (Ctrl-C then Esc) using vim-style notation',
+      '  aimux tab send "$TAB" "<C-c><Esc>" --keys',
+      '',
+      '  # follow a tab as NDJSON, one render (or tabStatus) per line',
+      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
+      '',
+    ].join('\n')
   )
   process.exit(0)
 }

package/src/platform/worktree-paths.ts

@@ -60,8 +60,15 @@ export async function assertSafeAimuxWorktreePath(path: string): Promise<void> {
   if (!isInsideAimuxWorktreeRoot(path)) {
     throw new Error(`refusing worktree path outside Aimux temp root: ${path}`)
   }
+  // Create the repo-scoped parent (<root>/r-<hash>) before resolving it: git
+  // worktree add does not create intermediate dirs, and realpath() would throw
+  // ENOENT on the first worktree for a repo. mkdir(recursive) leaves an
+  // existing symlink in place, so the realpath check below still catches an
+  // escape out of the temp root.
+  const parent = resolve(path, '..')
+  await mkdir(parent, { recursive: true })
   const realRoot = await realpath(root)
-  const realParent = await realpath(resolve(path, '..'))
+  const realParent = await realpath(parent)
   if (`${realParent}/`.startsWith(`${realRoot}/`)) return
   throw new Error(`unsafe Aimux worktree parent: ${realParent}`)
 }