The package family is split across several published packages in the babysitter

This specification defines the complete parameter surface for invoking agents through agent-mux: the RunOptions interface, supporting types (Attachment, RetryPolicy, McpServerConfig), the profile system for storing and resolving named option presets, and the validation, capability-gating, and resolution rules that govern how options flow from source to subprocess.

This specification defines the complete runtime interface for agent invocations: the RunHandle returned by mux.run(), the RunResult it resolves to, the InteractionChannel for building interactive UIs, the run state machine, subprocess lifecycle management, and all platform-specific behaviors.

Last refreshed: 2026-04-25

This specification defines the adapter system: the primary extension and abstraction layer that allows agent-mux to drive any CLI-based AI coding agent through a uniform interface. The adapter system consists of three core pieces:

This specification defines the capability discovery, model introspection, and thinking normalization systems in agent-mux. These three concerns are tightly related: capabilities determine what an agent can do, the model registry provides per-model granularity within those capabilities, and thinking normalization translates the unified thinkingEffort abstraction into each agent's native parameters.

The SessionManager provides read-only access to agent session data stored in each agent's native format and location. agent-mux does not own, replicate, or migrate session data -- it reads on demand, normalizes into unified types, and exposes a consistent query surface across all ten supported agents.

This specification defines two manager interfaces and their supporting types:

This specification defines the PluginManager interface and the complete plugin ecosystem for agent-mux. The plugin system provides a unified interface for discovering, installing, updating, and removing plugins across all supported agents, despite each agent having a fundamentally different native plugin architecture.

The amux binary is the CLI surface of the @a5c-ai/agent-mux project. It exposes every capability of the SDK -- running agents, inspecting adapters, managing sessions, configuring agents, handling authentication, working with plugins, and tracking costs -- through a single command-line interface.

This specification is the authoritative reference for subprocess management, process safety guarantees, and cross-platform support in @a5c-ai/agent-mux. It consolidates and deepens the process-lifecycle material introduced in 03-run-handle-and-interaction.md (sections 6–12), adds the full per-agent cross-platform compatibility matrix from scope §23, and specifies platform-specific path resolution, shell invocation, PTY backend selection, and resource cleanup in detail.

This specification defines the implementation details for all 13 built-in adapter implementations in @a5c-ai/agent-mux. Each adapter extends BaseAgentAdapter (spec 05 §4) and translates between the unified AgentAdapter interface and the native CLI of its target agent.

An invocation mode selects where a harness subprocess runs. The adapter contract is mode-agnostic: buildSpawnArgs() returns an abstract SpawnArgs { command, args, env, cwd, stdin?, shell? }, and a pure transform — buildInvocationCommand() — rewrites it into the concrete host command for the chosen mode.

Canonical package documentation lives in packages/agent-mux/harness-mock/README.md.

agent-mux provides a harness-agnostic hook system that lets one