# Feature Scout Brief

> The product surface, the features worth exploring first, and why those features deserve attention beyond the README.

- Repository: manaflow-ai/cmux
- GitHub: https://github.com/manaflow-ai/cmux
- Human wiki: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-5a511656cb1a
- Complete Markdown: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-5a511656cb1a/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `web/package.json`
- `Sources/cmuxApp.swift`
- `CLI/cmux.swift`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [package.json](package.json)
- [web/package.json](web/package.json)
- [Sources/cmuxApp.swift](Sources/cmuxApp.swift)
- [CLI/cmux.swift](CLI/cmux.swift)
- [docs/cli-contract.md](docs/cli-contract.md)
- [docs/events.md](docs/events.md)
- [CLI/CMUXCLI+AgentHookDefinitions.swift](CLI/CMUXCLI+AgentHookDefinitions.swift)
- [CLI/CMUXCLI+Events.swift](CLI/CMUXCLI+Events.swift)
- [Sources/Panels/BrowserAutomation.swift](Sources/Panels/BrowserAutomation.swift)
- [Sources/Cloud/VMClientSocketCommands.swift](Sources/Cloud/VMClientSocketCommands.swift)
- [web/services/vms/drivers/types.ts](web/services/vms/drivers/types.ts)
- [web/services/vms/drivers/index.ts](web/services/vms/drivers/index.ts)
- [web/services/vms/providerGateway.ts](web/services/vms/providerGateway.ts)
- [web/services/vms/workflows.ts](web/services/vms/workflows.ts)
- [web/services/vms/config.ts](web/services/vms/config.ts)
- [web/app/api/vm/route.ts](web/app/api/vm/route.ts)
- [web/app/api/vm/[id]/route.ts](web/app/api/vm/[id]/route.ts)
- [web/data/cmux.schema.json](web/data/cmux.schema.json)
- [docs/cloud-vm-backend-rollout-todo.md](docs/cloud-vm-backend-rollout-todo.md)
- [Sources/CommandPalette/CommandPaletteOverlay.swift](Sources/CommandPalette/CommandPaletteOverlay.swift)
- [Sources/ContentView+ViewCommandPalette.swift](Sources/ContentView+ViewCommandPalette.swift)
</details>

# Feature Scout Brief

cmux is easiest to understand as a set of composable local primitives: a native macOS terminal, embedded browser, workspace/sidebar model, notification system, CLI, socket API, event stream, and an emerging Cloud VM control plane. The README explains the product promise, but the codebase shows which features are mature enough to demo, extend, or copy into adjacent tools.

Knowledge-profile note: no `STRATEGY.md` or `docs/solutions/**` files were present in this checkout during the focused source pass, so this page uses repository code and docs as source of truth. The Compound Engineering profile was treated as bundled page-shape guidance, not as proof that a local installed skill ran.

Sources: [README.md:119-139](), [package.json:1-9](), [web/package.json:6-30]()

## Product Surface Map

```text
Native app              Local automation                 Web/control plane
----------              ----------------                 -----------------
Swift/AppKit app  <---> Unix socket + CLI + events <---> Next.js VM API
Ghostty terminal        browser commands                 provider gateway
workspace/sidebar       notifications/hooks              Postgres-backed VM workflow
embedded browser        custom actions/config            E2B/Freestyle drivers
```

The scout-worthy surface is not one feature; it is the way local UI, terminal automation, browser automation, and optional remote compute share handles for windows, workspaces, panes, surfaces, notifications, and VMs. The app entrypoint wires native app state, Ghostty environment setup, settings, notification commands, debug windows, workspace commands, and command-palette entrypoints. The CLI contract preserves stable command names and handle formats for scripting. The web package adds a Next.js backend with Cloud VM scripts and dependencies.

Sources: [Sources/cmuxApp.swift:25-86](), [Sources/cmuxApp.swift:206-245](), [Sources/cmuxApp.swift:286-327](), [Sources/cmuxApp.swift:500-579](), [docs/cli-contract.md:26-56](), [web/package.json:6-30]()

## Explore First

| Feature | Why it deserves attention beyond the README | Best first demo | Caution |
| --- | --- | --- | --- |
| Scriptable browser pane | It exposes agent-browser-style navigation, snapshots, actions, state, cookies, network, console, and trace commands from the CLI. | Open a browser split, navigate, snapshot, click/fill, then request `--snapshot-after`. | It depends on an existing browser surface for most commands. |
| Notification and event fabric | Notifications are not just UI badges; they are socket commands plus a reconnectable JSONL/event stream. | Trigger `cmux notify`, inspect notification panel, then stream `cmux events --category notification`. | Event payloads redact sensitive fields; consumers must use snapshots for catch-up. |
| Agent hook bridge | Hook definitions cover multiple coding agents and feed events, with per-agent config locations and disable env vars. | Install hooks for one supported agent and watch workspace/feed events. | Agent integrations differ by hook format and upstream support. |
| CLI/socket topology control | The CLI covers windows, workspaces, panes, surfaces, terminal input, browser actions, notifications, status/log metadata, and raw RPC. | Script a workspace with a split, terminal send, browser open, and status pill. | Preserve focus semantics; not every command should activate the app. |
| Cloud VMs | The CLI, native socket methods, Next.js routes, Effect workflows, and provider drivers form a provider-neutral remote workspace path. | `cmux vm new --provider e2b`, attach, exec, destroy in a configured environment. | Rollout docs show Freestyle blockers and operational TODOs, so treat as early-access infrastructure. |
| Configurable product surface | `cmux.json` supports actions, commands, hooks, UI wiring, app preferences, and workspace layouts. | Add a project-local action/command and invoke it from Command Palette or UI wiring. | Project-local commands need trust and portability review. |

Sources: [docs/cli-contract.md:57-168](), [CLI/cmux.swift:13229-13295](), [docs/events.md:1-32](), [CLI/CMUXCLI+AgentHookDefinitions.swift:122-297](), [web/data/cmux.schema.json:1-41]()

## Browser Automation Is A Product Primitive

The embedded browser is more than a visual panel. The CLI help exposes a broad automation grammar: open, navigate, snapshot, eval, wait, click, type, select, screenshot, query getters, accessibility-style finders, profiles, import, cookies, storage, tabs, console/errors, scripts/styles, viewport, geolocation, offline mode, trace, network routing, screencast, and raw input. That makes cmux a practical local harness for agents that need to inspect and operate a dev server without leaving the terminal/workspace model.

A small but important detail: `open`, `open-split`, and `new` can run without an explicit surface, while most operations require a surface handle. That keeps the model deterministic for agents: create or identify a browser surface, then operate on that handle.

```swift
// CLI/cmux.swift
Usage: cmux browser [--surface <id|ref|index> | <surface>] <subcommand> [args]
Browser automation commands. Most subcommands require a surface handle.
```

Browser import and profile management are also implemented as automation paths, not just settings UI. `BrowserImportAutomation.importCookies` detects installed browsers, selects source profiles, supports destination profile resolution/creation, and can filter imported cookies by domain. This is worth exploring because authenticated browser panes are often the difference between a toy demo and a useful agent workflow.

Sources: [CLI/cmux.swift:9705-9768](), [CLI/cmux.swift:10232-10494](), [CLI/cmux.swift:13229-13295](), [Sources/Panels/BrowserAutomation.swift:367-412](), [Sources/Panels/BrowserAutomation.swift:415-523]()

## Notifications, Sidebar State, And Events

The README frames notifications as blue rings, sidebar badges, and a panel. The deeper feature is that notifications, sidebar metadata, progress, logs, browser events, workspace lifecycle, surface input, and agent hooks can all flow through a reconnectable event stream. The event stream writes newline-delimited JSON over the existing cmux socket, starts with an ack frame, supports category/name filters, and has replay/cursor semantics.

That matters for extensions and Grok-Wiki-style product intelligence: a companion view can bootstrap from snapshots, subscribe to workspace/notification/sidebar events, and update derived state without polling. The event docs explicitly warn that prompt and input fields are redacted, so integrations should preserve local privacy boundaries and forward sensitive context only with user opt-in.

Sources: [README.md:125-129](), [docs/events.md:1-32](), [docs/events.md:34-93](), [CLI/CMUXCLI+Events.swift:19-103](), [docs/events.md:216-255](), [docs/events.md:297-342]()

## Agent Hooks Are Vendor-Agnostic Glue

cmux is not locked to a single coding agent. The hook definition table includes Codex, Grok, OpenCode, Pi, Amp, Cursor, Gemini, Antigravity, Rovo Dev, Hermes Agent, Copilot, CodeBuddy, Factory, and Qoder. Each definition names its config directory/file, binary or env override where relevant, session store suffix, disable env var, hook marker, format, lifecycle events, and feed-hook events.

This is one of the strongest BYOC/BYOK-friendly areas of the product. The integration shape is “adapt an agent’s lifecycle events into cmux notifications/feed/session state,” not “call one hosted model provider.” A scout should look for which agents have enough hook surface to support session start, prompt submit, stop, notification, permission/tool events, and session end.

Sources: [CLI/CMUXCLI+AgentHookDefinitions.swift:108-135](), [CLI/CMUXCLI+AgentHookDefinitions.swift:136-217](), [CLI/CMUXCLI+AgentHookDefinitions.swift:218-297](), [CLI/CMUXCLI+AgentHookDefinitions.swift:304-320]()

## CLI And Socket API Are The Integration Boundary

The CLI contract is unusually important because it documents behavior that must survive an implementation rewrite to Swift ArgumentParser. It requires no-socket help/version behavior, stable global options, JSON output where supported, `--id-format`, socket/password routing, and UUID/ref/index handles for windows, workspaces, panes, surfaces, and tabs.

For product scouts, this means cmux can be copied or extended as an automation substrate. Workflows should prefer stable CLI/socket commands over UI scraping: create workspaces, split panes, move surfaces, send input, read screens, control browser panes, manage notifications, and stream events. The raw `rpc` command is an escape hatch for v2 socket methods, but polished workflows should use named commands when they exist.

Sources: [docs/cli-contract.md:1-24](), [docs/cli-contract.md:57-168](), [CLI/cmux.swift:2669-2765](), [CLI/cmux.swift:3387-3390]()

## Cloud VMs Are The Remote Workspace Bet

Cloud VM support spans native CLI commands, app socket methods, authenticated Next.js REST routes, Effect-based workflows, and provider drivers. The CLI supports listing, creating, attaching/shelling, destroying, SSH info, and remote exec. The socket layer exposes `vm.list`, `vm.create`, `vm.destroy`, `vm.exec`, `vm.ssh_info`, and `vm.attach_info`. The REST layer keeps provider credentials behind server-side auth and ownership checks.

The provider contract is explicitly portable: `ProviderId` is currently `"e2b" | "freestyle"`, and callers go through a `VMProvider` interface with create/destroy/status/exec/snapshot/restore/attach/SSH/revoke operations. The gateway calls `getProvider(provider)` instead of embedding provider-specific logic in workflows. Runtime kill switches exist globally and per provider.

```ts
// web/services/vms/drivers/types.ts
export type ProviderId = "e2b" | "freestyle";

export interface VMProvider {
  create(options: CreateOptions): Promise<VMHandle>;
  destroy(vmId: string): Promise<void>;
  exec(vmId: string, command: string, opts?: { timeoutMs?: number }): Promise<ExecResult>;
  openAttach(vmId: string, options?: AttachOptions): Promise<AttachEndpoint>;
  openSSH(vmId: string): Promise<SSHEndpoint>;
}
```

The scout conclusion: this is the most strategically interesting surface, but not the safest first-copy feature. The rollout TODO says VM logic already runs in the Vercel Next app with Postgres state, while also noting Freestyle snapshot blockers and that E2B is the current staging/production default. Demo it only in configured environments and keep the architecture provider-neutral.

Sources: [CLI/cmux.swift:3146-3384](), [Sources/Cloud/VMClientSocketCommands.swift:3-74](), [web/app/api/vm/route.ts:1-45](), [web/app/api/vm/route.ts:93-229](), [web/app/api/vm/route.ts:231-327](), [web/app/api/vm/[id]/route.ts:12-31](), [web/services/vms/drivers/types.ts:1-18](), [web/services/vms/drivers/types.ts:76-104](), [web/services/vms/drivers/index.ts:8-30](), [web/services/vms/providerGateway.ts:17-76](), [web/services/vms/config.ts:6-35](), [docs/cloud-vm-backend-rollout-todo.md:5-20](), [docs/cloud-vm-backend-rollout-todo.md:41-56]()

## Customization And Command Palette

The config schema is a strong feature-scout signal because it turns cmux from an app into a local workflow host. Global `cmux.json` supports app settings, shortcuts, actions, custom commands, notification hooks, and workspace layouts. Project-local `.cmux/cmux.json` supports actions, commands, hooks, and UI action wiring. The schema describes `actions` as a registry used by the surface tab bar, Command Palette, shortcuts, and plus-button menu.

The command palette implementation is also worth scouting because it treats command rows as rendered state with IDs, titles, match indices, trailing labels, selected index, and stable row actions. Built-in command contributions include examples such as “Flash Focused Panel” and “Task Manager,” showing the pattern for adding locally discoverable actions without making every workflow a top-level menu item.

Sources: [web/data/cmux.schema.json:1-41](), [web/data/cmux.schema.json:158-175](), [Sources/CommandPalette/CommandPaletteOverlay.swift:14-31](), [Sources/CommandPalette/CommandPaletteOverlay.swift:64-158](), [Sources/ContentView+ViewCommandPalette.swift:3-32]()

## Grok-Wiki Integration Angle

A provider-neutral Grok-Wiki integration should present these features as cited, portable product cards rather than as model-provider-specific magic. The source adapters should accept file-backed pages, repository-backed source ranges, and catalog/skill-pack metadata as separate evidence classes. A good UI flow would let a reader filter by surface: “Native app,” “CLI/socket,” “Browser automation,” “Agent hooks,” “Cloud VM,” and “Config/customization.” Each card should show what to demo, what code owns it, what is mature, and what is still rollout-sensitive.

For BYOC/BYOK support, keep the integration boundary at local commands, event streams, config files, and provider interfaces. Do not assume a hosted model, a proprietary connector, or a single VM provider. The code already points in that direction: agent hooks are file/config based, browser automation is local socket driven, and Cloud VM providers sit behind a driver contract.

Sources: [CLI/CMUXCLI+AgentHookDefinitions.swift:122-297](), [docs/events.md:248-255](), [web/services/vms/drivers/types.ts:76-104](), [web/data/cmux.schema.json:1-41]()

## Final Scout Take

Start with browser automation, notifications/events, and CLI/socket topology because they are local, visible, and well documented in code. Then explore agent hooks as the vendor-neutral bridge into real coding-agent workflows. Treat Cloud VMs as the bigger product direction: highly promising, already wired through CLI/app/web/provider layers, but still carrying rollout caveats that deserve careful operational validation before broad productization.

Sources: [README.md:131-139](), [docs/cli-contract.md:57-168](), [CLI/cmux.swift:13229-13295](), [docs/cloud-vm-backend-rollout-todo.md:72-107]()