@brimveyn/aimux 1.19.6 → 1.20.1

package/README.md

@@ -157,6 +157,8 @@ The help modal reflects the resolved keymap, so it includes your overrides.
 
 ```bash
 aimux
+aimux worker doctor
+aimux worker run --name investigate --assistant claude "inspect this repository"
 aimux version
 aimux doctor
 aimux update
@@ -166,6 +168,10 @@ aimux restart-terminal-manager
 
 See [`docs/reference/cli.md`](docs/reference/cli.md) for behavior details.
 
+For agent orchestration, prefer the named `aimux worker` commands. They combine
+isolated worktree creation, prompt dispatch, authoritative turn waiting, fleet
+inspection, and guarded cleanup without shell wrappers or `jq`.
+
 ## Runtime Model
 
 `aimux` is split into:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.19.6",
+  "version": "1.20.1",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -34,6 +34,7 @@
   ],
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -65,7 +66,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.8.3",
+    "@brimveyn/aimux-config": "0.8.5",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/skills/aimux-orchestrator/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: aimux-orchestrator
+description: Orchestrate implementation plans with parallel Claude, Codex, OpenCode, Grok, or Kimi workers through the aimux worker CLI. Use when an agent must decompose a plan, launch isolated workers, supervise questions and failures, review each worker's diff and checks, integrate accepted work, and clean up safely.
+---
+
+# aimux Orchestrator
+
+Own the plan and quality gate. Let aimux own worker transport and lifecycle.
+
+## Preflight
+
+Run once:
+
+```bash
+aimux worker doctor
+aimux worker --help
+```
+
+Stop if the doctor reports missing worker capabilities, the wrong workspace, or
+an unavailable assistant. Restart/update aimux as instructed; do not fall back
+to screen scraping or the legacy shell wrappers.
+
+## Orchestration loop
+
+1. Parse the plan into independently reviewable units and dependencies.
+2. Record units in a ledger. Copy `assets/ledger.template.md` for multi-unit work.
+3. Select only units whose dependencies are accepted.
+4. Launch no more workers than you can review:
+
+```bash
+aimux worker run \
+  --name feat-auth \
+  --assistant claude \
+  --prompt-file /tmp/feat-auth.md \
+  --detach
+```
+
+5. Inspect the fleet with `aimux worker list`.
+6. Await a detached worker with `aimux worker await feat-auth`.
+7. If a worker asks a question, answer only when the plan already determines the
+   answer:
+
+```bash
+aimux worker prompt feat-auth --prompt-file /tmp/answer.md
+```
+
+Escalate design choices, irreversible operations, deployments, pushes,
+migrations, spending, and external communication to the human.
+
+8. Review the worktree path returned in the worker JSON. Read the diff and run
+   the repository's required tests, typecheck, lint, and build. Worker claims
+   are not evidence.
+9. Accept, request a precise correction with `worker prompt`, or escalate.
+10. After integration, close and clean up:
+
+```bash
+aimux worker stop feat-auth --cleanup-worktree
+```
+
+## Isolation
+
+`worker run` creates a fresh worktree by default. Keep that default when writes
+may overlap or scope is uncertain.
+
+- Use `--worktree <id>` only for workers intentionally sharing one review unit.
+- Use `--no-worktree` only for sequential work or provably disjoint writes in
+  the active tree.
+- Review co-located workers together because their diff is shared.
+
+## Dispatch rules
+
+- Give each worker one bounded unit with goal, scope, exclusions, acceptance
+  criteria, repository conventions, and required verification.
+- Read `references/prompts.md` when drafting task or correction prompts.
+- Use provider defaults unless the plan or user requires a model. Set
+  `--model`/`--effort` only when `worker doctor` says the assistant supports the
+  control.
+- Prefer `--prompt-file` for multiline prompts; it avoids shell quoting hazards.
+- Use `--detach` for parallel launch. Without it, `worker run` waits and returns
+  a completed/question/timeout/error outcome.
+
+## Quality and safety
+
+Read `references/review.md` before accepting the first unit.
+
+- `completed` means the turn ended, not that the change is correct.
+- Never accept a failing or unrun verification gate.
+- Cap correction attempts at three; then escalate with evidence.
+- Never use `--force` cleanup unless the human authorized discarding dirty work.
+- Keep the ledger truthful after every dispatch, outcome, review, and integration.
+
+The CLI is the command reference. Use `aimux worker <verb> --help` instead of
+copying flags or JSON shapes into this skill.

package/skills/aimux-orchestrator/assets/ledger.template.md

@@ -0,0 +1,18 @@
+# Orchestration ledger
+
+Base: `<branch / sha>`
+
+| unit | goal | deps | status  | worker | worktree / branch | attempts | review evidence |
+| ---- | ---- | ---- | ------- | ------ | ----------------- | -------: | --------------- |
+| 1.1  |      | —    | pending |        |                   |        0 |                 |
+
+Statuses: `pending`, `dispatched`, `in-review`, `needs-changes`, `accepted`,
+`blocked`, `escalated`.
+
+## Decisions
+
+- `<date>` — `<decision and reason>`
+
+## Human questions
+
+- [ ] `<unit>` — `<decision needed, evidence, and options>`

package/skills/aimux-orchestrator/references/prompts.md

@@ -0,0 +1,57 @@
+# Worker prompts
+
+## Task
+
+```markdown
+# Task: <id> — <title>
+
+## Goal
+
+<observable outcome>
+
+## Scope
+
+- In: <files or subsystem>
+- Out: <explicit exclusions>
+
+## Requirements
+
+1. <behavior>
+2. <edge case>
+
+## Acceptance
+
+- <machine-checkable criterion>
+
+## Verification
+
+Run the repository's tests, typecheck, lint, and build commands that apply.
+Report changed files, commands run, results, and remaining risks.
+```
+
+Tell the worker to read repository instructions before editing. Do not ask it to
+merge, push, deploy, or clean up its worktree.
+
+## Correction
+
+```markdown
+# Correction for <id>
+
+The review found:
+
+- <specific failing behavior with file/test evidence>
+
+Required change:
+
+- <bounded correction>
+
+Do not broaden scope. Re-run:
+
+- <exact verification commands>
+```
+
+## Answer
+
+Answer the exact question and restate any relevant boundary. If the question
+introduces a product decision or risky action not settled by the plan, escalate
+instead of improvising.

package/skills/aimux-orchestrator/references/review.md

@@ -0,0 +1,18 @@
+# Worker review gate
+
+Review inside the returned worktree path.
+
+1. Read repository instructions and the dispatched acceptance criteria.
+2. Inspect status and the complete diff against the unit's base.
+3. Confirm every changed hunk belongs to the requested scope.
+4. Check correctness, edge cases, error paths, tests, debug leftovers, secrets,
+   stubs, and repository conventions.
+5. Run the required test, typecheck, lint, format-check, and build commands
+   yourself.
+6. Record evidence in the ledger.
+
+Accept only when the behavior and verification pass. If a check cannot run,
+record why and escalate when it prevents a trustworthy decision.
+
+Request changes with concrete evidence: location, observed behavior, expected
+behavior, and the exact gate to rerun. Do not send a vague "fix the tests" prompt.

package/src/app-runtime/backend-runtime-events.ts

@@ -239,6 +239,11 @@ export function bindBackendRuntimeEvents({
     const current = appStore.getState()
     if (current.tabs.some((t) => t.id === tab.id)) {
       logInputDebug('app.backend.event.tabAdded.skipDuplicate', { sessionId, tabId: tab.id })
+      dispatch({
+        autoRenameStatus: tab.autoRenameStatus,
+        tabId: tab.id,
+        type: 'update-tab-metadata',
+      })
       return
     }
     if (current.currentSessionId !== sessionId) {
@@ -253,12 +258,22 @@ export function bindBackendRuntimeEvents({
     dispatch({ tab, type: 'add-tab' })
   }
 
+  const handleTabMetadataUpdated = (
+    sessionId: string,
+    tabId: string,
+    patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' }
+  ) => {
+    if (appStore.getState().currentSessionId !== sessionId) return
+    dispatch({ ...patch, tabId, type: 'update-tab-metadata' })
+  }
+
   backend.on('render', handleRender)
   backend.on('exit', handleExit)
   backend.on('error', handleError)
   backend.on('sessionActivity', handleSessionActivity)
   backend.on('tabActivity', handleTabActivity)
   backend.on('tabAdded', handleTabAdded)
+  backend.on('tabMetadataUpdated', handleTabMetadataUpdated)
   backend.on('workspaceCreateRequested', handleWorkspaceCreateRequested)
   backend.on('workspaceSwitchRequested', handleWorkspaceSwitchRequested)
   backend.on('workspaceCloseRequested', handleWorkspaceCloseRequested)
@@ -274,6 +289,7 @@ export function bindBackendRuntimeEvents({
     backend.off('sessionActivity', handleSessionActivity)
     backend.off('tabActivity', handleTabActivity)
     backend.off('tabAdded', handleTabAdded)
+    backend.off('tabMetadataUpdated', handleTabMetadataUpdated)
     backend.off('workspaceCreateRequested', handleWorkspaceCreateRequested)
     backend.off('workspaceSwitchRequested', handleWorkspaceSwitchRequested)
     backend.off('workspaceCloseRequested', handleWorkspaceCloseRequested)

package/src/app-runtime/side-effects.ts

@@ -329,7 +329,8 @@ export function startTabSession(
   tab: Pick<TabSession, 'id' | 'assistant' | 'title' | 'command' | 'worktreeId'>,
   cols: number,
   rows: number,
-  cwd?: string
+  cwd?: string,
+  autoRenameCandidate = true
 ): void {
   logInputDebug('app.tab.start.request', {
     cols,
@@ -357,6 +358,7 @@ export function startTabSession(
   backend.createSession({
     args,
     assistant: tab.assistant,
+    autoRenameCandidate,
     cols,
     command: executable,
     cwd,
@@ -613,7 +615,8 @@ function startExistingTab(ctx: SideEffectContext, tab: TabSession): void {
     tab,
     state.layout.terminalCols,
     state.layout.terminalRows,
-    getTabProjectPath(ctx, tab)
+    getTabProjectPath(ctx, tab),
+    false
   )
 }
 
@@ -874,6 +877,16 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       handleRenameSessionEffect(state.sessions, dispatch, effect.sessionId, effect.name)
       return
     }
+    case 'rename-tab': {
+      dispatch({
+        autoRenameStatus: 'attempted',
+        tabId: effect.tabId,
+        title: effect.title,
+        type: 'rename-tab',
+      })
+      backend.renameTab(effect.tabId, effect.title)
+      return
+    }
     case 'split-pane': {
       const sourceTab =
         effect.sourceTabId != null && effect.sourceTabId !== ''

package/src/auto-rename/coordinator.ts

@@ -0,0 +1,97 @@
+import type { AssistantId } from '../state/types'
+
+import { isSupportedProvider } from '../auto-commit/headless-commands'
+import { PromptCapture } from './prompt-capture'
+import { generateTabTitle, type TitleSpawnFn } from './title-runner'
+
+export interface AutoRenameConfigSnapshot {
+  enabled: boolean
+  timeoutMs: number
+  models: Partial<Record<string, string>>
+}
+
+export interface AutoRenameTab {
+  id: string
+  assistant: AssistantId
+  title: string
+  autoRenameStatus?: 'eligible' | 'attempted'
+}
+
+export interface AutoRenameCoordinatorOptions {
+  config: AutoRenameConfigSnapshot
+  getTab: (tabId: string) => AutoRenameTab | undefined
+  updateTab: (
+    tabId: string,
+    patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' }
+  ) => void
+  spawn?: TitleSpawnFn
+}
+
+export function initialAutoRenameStatus(
+  config: AutoRenameConfigSnapshot,
+  assistant: AssistantId,
+  candidate: boolean
+): 'eligible' | undefined {
+  return config.enabled && candidate && isSupportedProvider(assistant) ? 'eligible' : undefined
+}
+
+export class AutoRenameCoordinator {
+  private readonly captures = new Map<string, PromptCapture>()
+  private readonly controllers = new Map<string, AbortController>()
+
+  constructor(private readonly options: AutoRenameCoordinatorOptions) {}
+
+  register(tab: AutoRenameTab): void {
+    if (tab.autoRenameStatus === 'eligible' && !this.captures.has(tab.id)) {
+      this.captures.set(tab.id, new PromptCapture())
+    }
+  }
+
+  unregister(tabId: string): void {
+    this.controllers.get(tabId)?.abort()
+    this.controllers.delete(tabId)
+    this.captures.delete(tabId)
+  }
+
+  manualRename(tabId: string): void {
+    this.unregister(tabId)
+  }
+
+  observeWrite(tabId: string, input: string): void {
+    const tab = this.options.getTab(tabId)
+    if (!tab || tab.autoRenameStatus !== 'eligible') return
+    let capture = this.captures.get(tabId)
+    if (!capture) {
+      capture = new PromptCapture()
+      this.captures.set(tabId, capture)
+    }
+    const result = capture.feed(input)
+    if (result.type === 'pending') return
+
+    this.captures.delete(tabId)
+    this.options.updateTab(tabId, { autoRenameStatus: 'attempted' })
+    const prompt = result.prompt
+    if (prompt === null) return
+    const controller = new AbortController()
+    this.controllers.set(tabId, controller)
+    const originalTitle = tab.title
+
+    void (async () => {
+      const title = await generateTabTitle({
+        firstPrompt: prompt,
+        model: this.options.config.models[tab.assistant],
+        provider: tab.assistant,
+        signal: controller.signal,
+        spawn: this.options.spawn,
+        timeoutMs: this.options.config.timeoutMs,
+      })
+      if (this.controllers.get(tabId) !== controller) return
+      this.controllers.delete(tabId)
+      if (title == null || title === '') return
+      const current = this.options.getTab(tabId)
+      if (!current || current.autoRenameStatus !== 'attempted' || current.title !== originalTitle)
+        return
+      this.options.updateTab(tabId, { autoRenameStatus: 'attempted', title })
+    })()
+  }
+}

package/src/auto-rename/prompt-capture.ts

@@ -0,0 +1,211 @@
+const MAX_PROMPT_LENGTH = 8_000
+
+export type PromptCaptureResult = { type: 'pending' } | { type: 'submitted'; prompt: string | null }
+
+export class PromptCapture {
+  private chars: string[] = []
+  private cursor = 0
+  private escapeBuffer = ''
+  private bracketedPaste = false
+  private unreliable = false
+
+  feed(input: string): PromptCaptureResult {
+    for (const char of input) {
+      if (this.escapeBuffer !== '') {
+        this.feedEscape(char)
+        continue
+      }
+
+      if (char === '\x1b') {
+        this.escapeBuffer = char
+        continue
+      }
+
+      if (this.bracketedPaste) {
+        this.insert(char === '\r' ? '\n' : char)
+        continue
+      }
+
+      if (char === '\r' || char === '\n') {
+        if (this.unreliable) {
+          this.reset()
+          return { prompt: null, type: 'submitted' }
+        }
+        const prompt = this.value().trim()
+        this.reset()
+        if (prompt !== '') return { prompt, type: 'submitted' }
+        continue
+      }
+
+      if (char === '\x7f' || char === '\b') {
+        this.backspace()
+        continue
+      }
+      if (char === '\x01') {
+        this.cursor = 0
+        continue
+      }
+      if (char === '\x05') {
+        this.cursor = this.chars.length
+        continue
+      }
+      if (char === '\x02') {
+        this.cursor = Math.max(0, this.cursor - 1)
+        continue
+      }
+      if (char === '\x06') {
+        this.cursor = Math.min(this.chars.length, this.cursor + 1)
+        continue
+      }
+      if (char === '\x04') {
+        if (this.cursor < this.chars.length) this.chars.splice(this.cursor, 1)
+        continue
+      }
+      if (char === '\x0b') {
+        this.chars.splice(this.cursor)
+        continue
+      }
+      if (char === '\x15') {
+        this.chars = []
+        this.cursor = 0
+        continue
+      }
+      if (char === '\x17') {
+        this.deleteWord()
+        continue
+      }
+      if (char === '\x03') {
+        this.reset()
+        continue
+      }
+      if (char === '\x0c') continue
+      if (char < ' ' || char === '\x7f') {
+        this.invalidateCurrentSubmission()
+        continue
+      }
+      this.insert(char)
+    }
+    return { type: 'pending' }
+  }
+
+  reset(): void {
+    this.chars = []
+    this.cursor = 0
+    this.escapeBuffer = ''
+    this.bracketedPaste = false
+    this.unreliable = false
+  }
+
+  private value(): string {
+    return this.chars.join('').slice(0, MAX_PROMPT_LENGTH)
+  }
+
+  private insert(char: string): void {
+    if (this.chars.length >= MAX_PROMPT_LENGTH) return
+    this.chars.splice(this.cursor, 0, char)
+    this.cursor++
+  }
+
+  private backspace(): void {
+    if (this.cursor === 0) return
+    this.chars.splice(this.cursor - 1, 1)
+    this.cursor--
+  }
+
+  private deleteWord(): void {
+    while (this.cursor > 0 && /\s/u.test(this.chars[this.cursor - 1] ?? '')) this.backspace()
+    while (this.cursor > 0 && !/\s/u.test(this.chars[this.cursor - 1] ?? '')) this.backspace()
+  }
+
+  private feedEscape(char: string): void {
+    this.escapeBuffer += char
+    const sequence = this.escapeBuffer
+
+    if (
+      sequence.length === 2 &&
+      sequence !== '\x1b[' &&
+      sequence !== '\x1b]' &&
+      sequence !== '\x1bO'
+    ) {
+      this.escapeBuffer = ''
+      this.invalidateCurrentSubmission()
+      return
+    }
+
+    if (sequence.startsWith('\x1b]')) {
+      if (char === '\x07' || sequence.endsWith('\x1b\\')) this.escapeBuffer = ''
+      return
+    }
+
+    if (sequence.startsWith('\x1bO')) {
+      if (sequence.length < 3) return
+      this.escapeBuffer = ''
+      this.applyCursorSequence(sequence.at(-1) ?? '')
+      return
+    }
+
+    if (!sequence.startsWith('\x1b[')) return
+    if (sequence.length <= 2) return
+    if (!/[\x40-\x7e]$/u.test(char)) return
+
+    this.escapeBuffer = ''
+    switch (sequence) {
+      case '\x1b[200~':
+        this.bracketedPaste = true
+        return
+      case '\x1b[201~':
+        this.bracketedPaste = false
+        return
+      case '\x1b[1~':
+        this.cursor = 0
+        return
+      case '\x1b[4~':
+        this.cursor = this.chars.length
+        return
+      case '\x1b[3~':
+        if (this.cursor < this.chars.length) this.chars.splice(this.cursor, 1)
+        return
+    }
+
+    const final = sequence.at(-1) ?? ''
+    const parameters = sequence.slice(2, -1)
+    if ((final === 'C' || final === 'D') && parameters.includes(';')) {
+      this.invalidateCurrentSubmission()
+      return
+    }
+    const primaryParameter = parameters.split(';')[0]
+    const parsedCount = Number.parseInt(primaryParameter ?? '', 10)
+    const count = Number.isFinite(parsedCount) ? Math.max(1, parsedCount) : 1
+    this.applyCursorSequence(final, count)
+  }
+
+  private applyCursorSequence(final: string, count = 1): void {
+    switch (final) {
+      case 'A':
+      case 'B':
+        // History navigation replaces the editor buffer with content that was
+        // never sent through this input stream. Skip this submission rather
+        // than generating a title from an inaccurate reconstruction.
+        this.invalidateCurrentSubmission()
+        return
+      case 'D':
+        this.cursor = Math.max(0, this.cursor - count)
+        return
+      case 'C':
+        this.cursor = Math.min(this.chars.length, this.cursor + count)
+        return
+      case 'H':
+        this.cursor = 0
+        return
+      case 'F':
+        this.cursor = this.chars.length
+        return
+    }
+  }
+
+  private invalidateCurrentSubmission(): void {
+    this.chars = []
+    this.cursor = 0
+    this.unreliable = true
+  }
+}