teamleaderleo · Oct 19, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
@@ -177,7 +177,7 @@ jobs:
             url "https://github.com/manaflow-ai/cmux/releases/download/v#{version}/cmux-macos.dmg"
             name "cmux"
             desc "Lightweight native macOS terminal with vertical tabs for AI coding agents"
-            homepage "https://cmux.com"
+            homepage "https://cmux.com/"
 
             livecheck do
               url :url
@@ -188,6 +188,7 @@ jobs:
 
             app "cmux.app"
             binary "#{appdir}/cmux.app/Contents/Resources/bin/cmux"
+            generate_completions_from_executable "#{HOMEBREW_PREFIX}/bin/cmux", "completion"
 
             zap trash: [
               "~/Library/Application Support/cmux",

diff --git a/CLI/CMUXCLI+AgentHookCatalog.swift b/CLI/CMUXCLI+AgentHookCatalog.swift
@@ -283,6 +283,19 @@ extension CMUXCLI {
         ),
     ]
 
+    /// The agents `cmux hooks <agent> ...` and `cmux hooks setup --agent <name>`
+    /// accept, derived from the same catalog `agentDef(named:)` resolves against,
+    /// so catalog aliases are offered alongside primary names.
+    static let hookAgentNames: [String] = Set(agentDefs.flatMap { [$0.name] + $0.aliases }).sorted()
+
+    /// Completion candidates for the first token of `cmux hooks`: the
+    /// catalog-wide verbs `cmux hooks --help` documents plus every agent. `hooks`
+    /// stays an unrecognized-argument sink rather than a subcommand tree because
+    /// past the first token it dispatches into the per-agent event entrypoints
+    /// that generated configs own, and declaring those would put internal hook
+    /// events in the user-facing tree.
+    static let hooksTargetNames: [String] = ["setup", "uninstall", "feed"] + hookAgentNames
+
     static func agentDef(named name: String) -> AgentHookDef? {
         let normalized = name.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
         return agentDefs.first { $0.name == normalized || $0.aliases.contains(normalized) }

diff --git a/CLI/CMUXCLI+CommandSuggestions.swift b/CLI/CMUXCLI+CommandSuggestions.swift
@@ -50,199 +50,5 @@ extension CMUXCLI {
         return previous[right.count]
     }
 
-    static let topLevelCommandNames: Set<String> = [
-        "__codex-teams-watch",
-        "__internal_flags",
-        "__sidebar_footer_icon_balance",
-        "__tmux-compat",
-        "agent",
-        "agent-hibernation",
-        "ai-accounts",
-        "automation",
-        "auth",
-        "bind-key",
-        "break-pane",
-        "browser",
-        "browser-back",
-        "browser-forward",
-        "browser-reload",
-        "browser-status",
-        "capabilities",
-        "capture-pane",
-        "claude-hook",
-        "claude-teams",
-        "clear-history",
-        "clear-log",
-        "clear-notifications",
-        "clear-progress",
-        "clear-status",
-        "close-surface",
-        "close-window",
-        "close-workspace",
-        "cloud",
-        "coderouter",
-        "cr",
-        "codex",
-        "codex-hook",
-        "codex-teams",
-        "comments",
-        "config",
-        "copy-mode",
-        "current",
-        "current-window",
-        "current-workspace",
-        "debug-terminals",
-        "detach-tab",
-        "diff",
-        "disable-browser",
-        "dismiss-notification",
-        "display-message",
-        "docs",
-        "drag-surface-to-split",
-        "enable-browser",
-        "events",
-        "feedback",
-        "feed",
-        "feed-hook",
-        "fork",
-        "find-window",
-        "focus-pane",
-        "focus-panel",
-        "focus-webview",
-        "focus-window",
-        "get-url",
-        "glaeda",
-        "help",
-        "hooks",
-        "identify",
-        "import",
-        "is-webview-focused",
-        "ios",
-        "join-pane",
-        "jump-to-last-prompt",
-        "jump-to-unread",
-        "last-pane",
-        "last-window",
-        "list-buffers",
-        "list-log",
-        "list-notifications",
-        "list-pane-surfaces",
-        "list-panels",
-        "list-panes",
-        "list-status",
-        "list-windows",
-        "list-workspaces",
-        "log",
-        "login",
-        "logout",
-        "local-tmux",
-        "local-zellij",
-        "markdown",
-        "mark-notification-read",
-        "memory",
-        "mobile",
-        "mosh",
-        "mosh-tmux",
-        "move-surface",
-        "move-tab-to-new-workspace",
-        "move-workspace-to-window",
-        "navigate",
-        "new-pane",
-        "new-split",
-        "new-surface",
-        "new-window",
-        "new-workspace",
-        "next-window",
-        "notify",
-        "omc",
-        "omo",
-        "omx",
-        "open",
-        "open-browser",
-        "open-notification",
-        "paste",
-        "paste-buffer",
-        "ping",
-        "pipe-pane",
-        "popup",
-        "pr",
-        "previous-window",
-        "read-screen",
-        "read-selection",
-        "record",
-        "refresh-surfaces",
-        "reload-config",
-        "remote-daemon-status",
-        "rename-tab",
-        "rename-window",
-        "rename-workspace",
-        "reorder-surface",
-        "reorder-workspace",
-        "reorder-workspaces",
-        "resize-pane",
-        "resize-window",
-        "respawn-pane",
-        "restore-session",
-        "restore",
-        "right-sidebar",
-        "rpc",
-        "screenshot",
-        "select-workspace",
-        "send",
-        "send-key",
-        "send-key-panel",
-        "send-panel",
-        "session",
-        "sessions",
-        "set-app-focus",
-        "set-buffer",
-        "set-hook",
-        "set-progress",
-        "set-status",
-        "settings",
-        "setup-hooks",
-        "shortcuts",
-        "shot",
-        "socket-status",
-        "simulate-app-active",
-        "simulator",
-        "sidebar",
-        "sidebar-state",
-        "split-off",
-        "ssh",
-        "ssh-pty-attach",
-        "ssh-session-attach",
-        "ssh-session-cleanup",
-        "ssh-session-end",
-        "ssh-session-list",
-        "ssh-tmux",
-        "sudo",
-        "surface",
-        "surface-health",
-        "surface-resume",
-        "swap-pane",
-        "tab-action",
-        "themes",
-        "tmux",
-        "todo",
-        "top",
-        "tree",
-        "trigger-flash",
-        "unbind-key",
-        "uninstall-hooks",
-        "vault",
-        "version",
-        "vm",
-        "vm-pty-attach",
-        "vm-pty-connect",
-        "vm-ssh-attach",
-        "vm-tui-approve",
-        "vm-tui-connect",
-        "vpn",
-        "wait-for",
-        "welcome",
-        "workspace",
-        "workspace-action",
-        "workspace-group",
-    ]
+    static let topLevelCommandNames: Set<String> = CmuxCommand.declaredCommandNames
 }
diff --git a/CLI/CMUXCLI+CommandTreeDump.swift b/CLI/CMUXCLI+CommandTreeDump.swift
@@ -0,0 +1,128 @@
+import Foundation
+
+extension CMUXCLI {
+    func runDumpCommandTree() throws {
+        let data = Data(CmuxCommand._dumpHelp().utf8)
+        let toolInfo = try JSONDecoder().decode(CommandTreeToolInfo.self, from: data)
+        // ArgumentParser synthesizes its own "help" subcommand alongside any
+        // explicitly declared one with the same name, so the same path can
+        // appear twice; keep one entry per path.
+        var seenPaths: Set<String> = []
+        let entries = commandTreeEntries(from: toolInfo.command)
+            .sorted { $0.path < $1.path }
+            .filter { seenPaths.insert($0.path).inserted }
+
+        for entry in entries {
+            print("command  \(entry.path)  aliases=\(entry.aliases)")
+            for argument in entry.arguments.sorted(by: { $0.name < $1.name }) {
+                print("  arg  \(argument.name)  kind=\(argument.kind)  completion=\(argument.completion)")
+            }
+        }
+    }
+
+    private func commandTreeEntries(from root: CommandTreeCommandInfo) -> [CommandTreeEntry] {
+        root.subcommands
+            .flatMap { commandTreeEntries(from: $0, path: []) }
+    }
+
+    private func commandTreeEntries(
+        from command: CommandTreeCommandInfo,
+        path: [String]
+    ) -> [CommandTreeEntry] {
+        let path = path + [command.commandName]
+        let entry = CommandTreeEntry(
+            path: path.joined(separator: " "),
+            aliases: command.aliases?.sorted().joined(separator: ",") ?? "-",
+            arguments: command.arguments
+                .filter { $0.preferredName?.rendered != "--help" }
+                .map(CommandTreeArgumentEntry.init)
+        )
+        return [entry] + command.subcommands.flatMap { commandTreeEntries(from: $0, path: path) }
+    }
+}
+
+private struct CommandTreeToolInfo: Decodable {
+    let command: CommandTreeCommandInfo
+}
+
+private struct CommandTreeCommandInfo: Decodable {
+    let commandName: String
+    let aliases: [String]?
+    let subcommands: [CommandTreeCommandInfo]
+    let arguments: [CommandTreeArgumentInfo]
+
+    private enum CodingKeys: String, CodingKey {
+        case commandName
+        case aliases
+        case subcommands
+        case arguments
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        commandName = try container.decode(String.self, forKey: .commandName)
+        aliases = try container.decodeIfPresent([String].self, forKey: .aliases)
+        subcommands = try container.decodeIfPresent([CommandTreeCommandInfo].self, forKey: .subcommands) ?? []
+        arguments = try container.decodeIfPresent([CommandTreeArgumentInfo].self, forKey: .arguments) ?? []
+    }
+}
+
+private struct CommandTreeArgumentInfo: Decodable {
+    let kind: String
+    let preferredName: CommandTreeArgumentName?
+    let valueName: String?
+    let completionKind: CommandTreeCompletionKind?
+}
+
+private struct CommandTreeArgumentName: Decodable {
+    let kind: String
+    let name: String
+
+    var rendered: String {
+        switch kind {
+        case "long": "--\(name)"
+        case "short", "longWithSingleDash": "-\(name)"
+        default: name
+        }
+    }
+}
+
+private enum CommandTreeCompletionKind: Decodable {
+    case list(values: [String])
+    case file(extensions: [String])
+    case directory
+    case shellCommand(command: String)
+    case custom
+    case customAsync
+    case customDeprecated
+
+    var rendered: String {
+        switch self {
+        case .list(let values): "list(\(values.sorted().joined(separator: ",")))"
+        case .file(let extensions): "file(\(extensions.sorted().joined(separator: ",")))"
+        case .directory: "directory"
+        case .shellCommand(let command): "shell-command(\(command))"
+        case .custom: "custom"
+        case .customAsync: "custom-async"
+        case .customDeprecated: "custom-deprecated"
+        }
+    }
+}
+
+private struct CommandTreeEntry {
+    let path: String
+    let aliases: String
+    let arguments: [CommandTreeArgumentEntry]
+}
+
+private struct CommandTreeArgumentEntry {
+    let name: String
+    let kind: String
+    let completion: String
+
+    init(_ argument: CommandTreeArgumentInfo) {
+        name = argument.preferredName?.rendered ?? argument.valueName ?? "-"
+        kind = argument.kind == "positional" ? "argument" : argument.kind
+        completion = argument.completionKind?.rendered ?? "-"
+    }
+}
diff --git a/CLI/CMUXCLI+Config.swift b/CLI/CMUXCLI+Config.swift
@@ -3,6 +3,17 @@ import CmuxFoundation
 import CmuxSettings
 
 extension CMUXCLI {
+    /// Completion candidates for `cmux config`, matching the subcommands the
+    /// runner switches on and `configUsage()` documents. Canonical spellings
+    /// only; `check`/`validate`/`paths`/`documentation` still resolve.
+    static let configSubcommandNames = [
+        "doctor", "path", "docs", "reload", "get", "set",
+        "unset", "toggle", "cycle", "preset",
+        CmuxGhosttyConfigSettingEditor.sidebarFontSizeKey,
+        CmuxGhosttyConfigSettingEditor.surfaceTabBarFontSizeKey,
+        "help",
+    ]
+
     func runConfigCommand(
         commandArgs: [String],
         socketPath: String?,