CLI Reference (amux)

Specification v1.0 | @a5c-ai/agent-mux-cli

SCOPE EXTENSION: hermes-agent (@NousResearch/hermes-agent) is included as a 10th supported agent per explicit project requirements from the project owner. It extends the original scope document's 9 built-in agents. All hermes-specific content in this spec is marked with this same scope extension note.

---

1. Overview

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.

The CLI and SDK are co-equal surfaces that share the same core layer and behave identically. Every CLI command maps to a specific SDK method. This specification defines the CLI completely and precisely: a developer should be able to implement the binary from this document alone.

1.1 Package Coordinates

Field	Value
npm package	@a5c-ai/agent-mux-cli
Binary name	amux
Language	TypeScript, strict mode
Runtime	Node.js 20.9.0 or later
License	MIT

The binary is installed as part of @a5c-ai/agent-mux (the convenience meta-package) or standalone via @a5c-ai/agent-mux-cli. It depends on @a5c-ai/agent-mux-core and @a5c-ai/agent-mux-adapters.

# Via meta-package
npm install -g @a5c-ai/agent-mux

# Standalone CLI
npm install -g @a5c-ai/agent-mux-cli

# Zero-install
npx @a5c-ai/agent-mux
npx @a5c-ai/agent-mux run claude "hello"

1.2 Cross-References

Concept	Spec	Section
AgentName, BuiltInAgentName	01-core-types-and-client.md	1.4
ErrorCode, AgentMuxError	01-core-types-and-client.md	3.1
CapabilityError	01-core-types-and-client.md	3.2
ValidationError	01-core-types-and-client.md	3.3
Storage layout	01-core-types-and-client.md	4
createClient(), ClientOptions	01-core-types-and-client.md	5
RunOptions	02-run-options-and-profiles.md	2
ProfileManager	02-run-options-and-profiles.md	10
RunHandle, RunResult	03-run-handle-and-interaction.md	2, 3
AgentEvent union	04-agent-events.md	2
AgentAdapter, BaseAgentAdapter	05-adapter-system.md	2
AgentCapabilities, ModelCapabilities	06-capabilities-and-models.md	2
SessionManager	07-session-manager.md	2
ConfigManager, AuthManager	08-config-and-auth.md	2, 8
PluginManager	09-plugin-manager.md	2
CLI commands (scope)	agent-mux-scope.md	21
Process lifecycle (scope)	agent-mux-scope.md	22
Package structure (scope)	agent-mux-scope.md	24

---

2. Invocation Syntax

amux [command] [subcommand] [positional-args...] [flags...]

When invoked without a command, amux prints a help summary and exits with code 0.

When invoked with an unrecognized command, amux prints an error message with suggestions and exits with code 2.

---

3. Global Flags

Global flags are accepted by every command. They are parsed before command-specific flags and override corresponding environment variables and config file values.

Flag	Short	Type	Default	Description
--agent	-a	AgentName	Config default	Target agent name. Accepted values: claude, codex, gemini, copilot, cursor, opencode, pi, omp, openclaw, hermes, or any plugin-registered adapter name.
--model	-m	string	Agent default	Model ID for the target agent. Must be a model ID recognized by the agent's adapter.
--json	--	boolean	false	Output as machine-readable JSON or JSONL. See Section 5 for output mode details.
--debug	--	boolean	false	Enable debug output. Includes raw event data in JSONL output and verbose logging to stderr.
--config-dir	--	string	~/.agent-mux/	Override the global configuration directory. Equivalent to createClient({ configDir }).
--project-dir	--	string	.agent-mux/	Override the project-local configuration directory. Equivalent to createClient({ projectConfigDir }).
--no-color	--	boolean	false	Disable colored output. Also activated when the NO_COLOR environment variable is set to any non-empty value, or when stdout is not a TTY.
--version	-V	boolean	--	Print the @a5c-ai/agent-mux-cli version and exit.
--help	-h	boolean	--	Print help for the current command and exit. Available on every command and subcommand.
--completions	--	string	--	Generate shell completion script: bash, zsh, fish, powershell. See Section 22.

3.1 Flag Parsing Rules

• Long flags use --kebab-case (e.g., --thinking-effort, --config-dir).
• Short flags are single-character prefixed with - (e.g., -a, -m, -i, -q, -y).
• Boolean flags do not take a value (--json enables JSON mode; --no-stream disables streaming).
• Repeatable flags accept multiple values by specifying the flag multiple times (e.g., --tag build --tag test).
• --env flags use KEY=VALUE syntax (e.g., --env ANTHROPIC_API_KEY=sk-...).
• -- terminates flag parsing; all subsequent arguments are treated as positional.

---

4. Exit Codes

The amux binary uses the following exit codes. These are the only exit codes produced by the CLI itself. When amux run is used, the agent subprocess exit code is available in the JSONL output but does not propagate as the amux process exit code unless the agent crashed.

Code	Name	Description	Corresponding ErrorCode
0	Success	Command completed successfully.	--
1	General error	An error occurred during execution.	Varies (see error event)
2	Usage error	Invalid command syntax, unknown flag, or missing required argument.	VALIDATION_ERROR
3	Agent not found	The specified agent has no registered adapter.	AGENT_NOT_FOUND
4	Agent not installed	The agent adapter exists but the CLI binary is not on $PATH.	AGENT_NOT_INSTALLED
5	Auth error	Authentication is required but not configured or expired.	AUTH_ERROR
6	Capability error	The requested operation requires a capability the agent does not support.	CAPABILITY_ERROR
7	Config error	Configuration file could not be read, parsed, or written.	CONFIG_ERROR
8	Session not found	The specified session does not exist.	SESSION_NOT_FOUND
9	Profile not found	The specified profile does not exist.	PROFILE_NOT_FOUND
10	Plugin error	Plugin operation failed (install, uninstall, search, etc.).	PLUGIN_ERROR
11	Timeout	The run exceeded its timeout or inactivity timeout.	TIMEOUT or INACTIVITY_TIMEOUT
12	Agent crashed	The agent subprocess terminated unexpectedly.	AGENT_CRASH
13	Aborted	The run was aborted by the user (e.g., via SIGINT).	ABORTED
14	Rate limited	The agent reported a rate limit.	RATE_LIMITED
15	Context exceeded	The agent's context window was exceeded.	CONTEXT_EXCEEDED

4.1 Exit Code Mapping

The CLI maps ErrorCode values from the SDK to exit codes as shown above. When multiple errors occur, the exit code reflects the first fatal error. Non-fatal errors (e.g., RATE_LIMITED with a successful retry) do not affect the exit code.

The following ErrorCode values map to exit code 1 (General error) as they have no dedicated exit code:

ErrorCode	Rationale
SPAWN_ERROR	Agent subprocess failed to spawn (bad path, permissions, missing binary). Distinct from AGENT_NOT_INSTALLED (binary not found on PATH) in that the binary was found but could not be executed.
INTERNAL	Internal agent-mux error (bug). Should not occur in normal operation.
PARSE_ERROR	An agent's output could not be parsed. Distinct from CONFIG_ERROR in that it relates to runtime output, not config files.

Note: CONFIG_LOCK_ERROR maps to exit code 7 (same as CONFIG_ERROR), not exit code 1, since it is a config-related error. It is not listed in the exit code 1 table above.

---

5. Output Modes

The CLI supports three output modes, selected by flags and context.

5.1 Human-Readable (Default)

When stdout is a TTY and --json is not set, the CLI produces formatted, colored output:

• Tables: aligned columns with headers for list commands (adapters list, sessions list, models list, etc.).
• Streaming text: for amux run, agent text output is printed to stdout as it arrives. Tool calls, thinking, and file operations are printed to stderr with visual indicators.
• Progress indicators: spinners and status lines for long-running operations (install, plugin operations).
• Color: ANSI color codes for emphasis, status indicators, and error highlighting. Disabled by --no-color, NO_COLOR env var, or non-TTY stdout.

5.2 JSON (--json)

When --json is set on non-streaming commands (e.g., adapters list --json, sessions list --json, models list --json), the CLI outputs a single JSON object or array to stdout:

{
  "ok": true,
  "data": [ ... ]
}

On error:

{
  "ok": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No adapter registered for agent 'foo'",
    "recoverable": false
  }
}

5.3 JSONL Event Stream (amux run --json)

When --json is set on amux run, the CLI outputs one JSON object per line to stdout. Each line is a serialized AgentEvent object as defined in 04-agent-events.md. The final line is always a RunResult object with type: "run_result".

{"type":"session_start","runId":"01J...","agent":"claude","timestamp":1718000000000,"sessionId":"abc123","resumed":false}
{"type":"text_delta","runId":"01J...","agent":"claude","timestamp":1718000000100,"delta":"Hello","accumulated":"Hello"}
{"type":"message_stop","runId":"01J...","agent":"claude","timestamp":1718000000200,"text":"Hello, world!"}
{"type":"run_result","runId":"01J...","agent":"claude","model":"claude-sonnet-4-20250514","sessionId":"abc123","text":"Hello, world!","exitCode":0,"exitReason":"completed","durationMs":1200,"turnCount":1}

When --debug is combined with --json, each event includes the raw field containing the unparsed agent output line.

Human-readable progress (spinners, status) is suppressed in JSONL mode. Diagnostic messages go to stderr.

---

6. amux run -- Run an Agent

Invoke an agent with a prompt. This is the primary command.

6.1 Syntax

amux run [<agent>] [<prompt>] [flags...]

Both <agent> and <prompt> are optional positional arguments:

• If <agent> is omitted, the default agent from config is used (GlobalConfig.defaultAgent or --agent global flag).
• If --prompt / -p is provided, it supplies the initial prompt and takes precedence over positional prompt text.
• If no explicit prompt is provided and stdin is not a TTY, the prompt is read from stdin (see Section 14).
• If no explicit prompt is provided and stdin is a TTY and --interactive is not set, the CLI prints an error and exits with code 2.
• If both are provided as positionals, the first argument is parsed as an agent name if it matches a registered adapter; otherwise, the entire positional is treated as the prompt and the default agent is used.

6.2 Flags

Flag	Short	Type	Default	Maps to RunOptions	Description
--model	-m	string	Agent default	model	Model ID.
--stream	--	boolean	true	stream: true	Enable streaming output.
--no-stream	--	boolean	--	stream: false	Disable streaming; buffer all output.
--thinking-effort	--	string	--	thinkingEffort	Thinking effort: low, medium, high, max.
--thinking-budget	--	number	--	thinkingBudgetTokens	Thinking budget in tokens. Minimum 1024.
--temperature	--	number	--	temperature	Sampling temperature (0.0–2.0). Capability-gated.
--top-p	--	number	--	topP	Top-p sampling (0.0–1.0). Capability-gated.
--top-k	--	number	--	topK	Top-k sampling (>= 1). Capability-gated.
--thinking-override	--	string	--	thinkingOverride	Native thinking parameter override as a JSON string. Passed directly to the agent's API. Use for agent-specific thinking controls not covered by --thinking-effort or --thinking-budget. Example: --thinking-override '{"type":"enabled","budget_tokens":8192}'.
--max-tokens	--	number	--	maxTokens	Maximum output tokens.
--max-output-tokens	--	number	--	maxOutputTokens	Alias for --max-tokens. If both are set, --max-output-tokens wins.
--max-turns	--	number	--	maxTurns	Maximum agentic turns (tool-use loops).
--session	--	string	--	sessionId	Resume session by native session ID.
--fork	--	string	--	forkSessionId	Fork session by native session ID.
--no-session	--	boolean	false	noSession: true	Ephemeral run; do not persist session.
--system	--	string	--	systemPrompt	System prompt text.
--system-mode	--	string	prepend	systemPromptMode	System prompt mode: prepend, append, replace.
--cwd	--	string	process.cwd()	cwd	Working directory for the agent subprocess. Must be an absolute path to an existing directory.
--env	--	string	--	env	Environment variable in KEY=VALUE format. Repeatable.
--prompt	-p	string	--	--	Initial prompt text. Equivalent to the positional <prompt>, but unambiguous in scripts.
--non-interactive	--	boolean	false	nonInteractive: true	Force headless one-shot harness mode. Harness prompt flags are only used when this is paired with --prompt.
--yolo	--	boolean	--	approvalMode: 'yolo'	Auto-approve all tool calls and file operations.
--deny	--	boolean	--	approvalMode: 'deny'	Auto-deny all actions requiring approval.
--timeout	--	number	0	timeout	Run timeout in milliseconds. 0 disables.
--inactivity-timeout	--	number	0	inactivityTimeout	Inactivity timeout in milliseconds. 0 disables.
--output-format	--	string	text	outputFormat	Agent output format: text, json, jsonl.
--tag	--	string	--	tags	Run tag for cost roll-ups and session search. Repeatable.
--run-id	--	string	Auto ULID	runId	Custom run ID (must be a valid ULID).
--attach	--	string	--	attachments	File path to attach. Repeatable. Supports images and text files. Capability-gated (supportsFileAttachments).
--skill	--	string	--	skills	Skill file or directory path. Repeatable. Capability-gated (supportsSkills).
--agents-doc	--	string	--	agentsDoc	Path to an agents.md document. Capability-gated (supportsAgentsMd).
--mcp-server	--	string	--	mcpServers	MCP server name (must exist in config). Repeatable. Overrides the default MCP server set. Capability-gated (supportsMCP).
--project-id	--	string	--	projectId	Project identifier for cost tracking and session grouping. Stored in run-index.jsonl.
--profile	--	string	--	profile	Named profile to apply as the base.
--interactive	-i	boolean	false	--	Enter interactive REPL mode (see Section 13).
--json	--	boolean	false	--	Emit JSONL event stream to stdout.
--quiet	-q	boolean	false	--	Suppress non-essential output (tool calls, thinking, file ops). Only print final text.

SDK-Only RunOptions (No CLI Flag)

The following RunOptions fields are intentionally not exposed as CLI flags:

RunOptions Field	Reason
retryPolicy	Complex RetryPolicy object with maxRetries, baseDelay, maxDelay, backoffMultiplier fields. Not suitable for a single CLI flag. Configure via profile or config file.
onInputRequired	Callback function. The CLI handles input_required events internally (prompts user or auto-denies in non-interactive mode).
onApprovalRequest	Callback function. The CLI handles approval_request events via --yolo / --deny flags or interactive prompts.

6.3 Mutual Exclusion

The following flag combinations are invalid and produce exit code 2:

• --session + --no-session
• --session + --fork
• --fork + --no-session
• --yolo + --deny
• --stream + --no-stream

6.4 Flag-to-RunOptions Mapping

The CLI constructs a RunOptions object from flags. Resolution order (highest precedence first):

1. Explicit CLI flags.
2. Profile values (if --profile is set).
3. Project config values (.agent-mux/config.json).
4. Global config values (~/.agent-mux/config.json).
5. Adapter defaults.

This matches the resolution order defined in 02-run-options-and-profiles.md, Section 7.

6.5 Behavior

1. The CLI calls createClient() with global flag overrides.
2. Resolves the initial prompt from --prompt, positional args, or stdin.
3. Constructs RunOptions from flags, profile, and config.
4. Calls mux.run(options) to obtain a RunHandle.
5. By default, the initial prompt is delivered to stdin-capable harnesses over stdin so the harness stays interactive. When --prompt and --non-interactive are both set, agent-mux instead uses the harness's one-shot prompt flag/path.
6. Consumes events from the RunHandle:
   • Human mode: prints text deltas to stdout, tool calls and thinking to stderr.
   • JSONL mode (--json): writes each AgentEvent as one JSON line to stdout.
   • Quiet mode (-q): suppresses everything except the final message_stop text.
7. On approval_request events (when approvalMode is 'prompt' and not --yolo/--deny):
   • Interactive terminal: prompts the user on stderr, reads response from stdin.
   • Non-interactive (pipe, no TTY): auto-denies with a warning to stderr.
8. On input_required events:
   • Interactive terminal: prompts on stderr, reads from stdin.
   • Non-interactive: emits the event in JSONL mode; otherwise errors.
9. Awaits RunResult. Prints cost summary to stderr (unless --quiet).
10. Exits with the appropriate exit code (see Section 4).

6.6 API Mapping

CLI	SDK
amux run claude "hello"	mux.run({ agent: 'claude', prompt: 'hello' })
amux run --profile fast "hello"	mux.run({ profile: 'fast', prompt: 'hello' })
amux run -a gemini --yolo "fix tests"	mux.run({ agent: 'gemini', prompt: 'fix tests', approvalMode: 'yolo' })

6.7 Examples

# Basic run
amux run claude "explain this codebase"

# Run with thinking and model override
amux run claude --model claude-sonnet-4-20250514 --thinking-effort high "refactor auth module"

# Ephemeral run with auto-approve
amux run codex --no-session --yolo "add unit tests for utils.ts"

# Resume session
amux run claude --session abc123 "continue from where we left off"

# Fork session
amux run claude --fork abc123 "try a different approach"

# JSONL output for piping
amux run gemini --json "list all TODO items" | jq 'select(.type == "text_delta") | .delta'

# With tags for cost tracking
amux run claude --tag feature/auth --tag sprint-42 "implement oauth flow"

# Using a profile
amux run --profile careful "review this PR"

# Quiet mode -- only final text
amux run claude -q "what is 2+2"

---

6b. amux launch -- Launch a Harness with Provider Flexibility

Start (or resume) an interactive or non-interactive coding agent session with full stdin/stdout passthrough. Unlike amux run, which normalizes output into the AgentEvent stream, amux launch is a transparent proxy — the user interacts directly with the harness as if they invoked it natively. Its key additional capability is unified provider resolution: you can point any supported harness at any LLM provider, with amux-proxy bridging the gap when the harness cannot speak the provider's native wire protocol.

See launcher for the archived launcher specification and provider & model configuration for the archived provider-configuration design.

Concern	amux run	amux launch
Output format	Normalized AgentEvent stream	Raw harness output (bypass)
Input format	RunOptions / SDK API	Raw stdin passthrough
Provider config	N/A (each harness's own)	Unified provider/model resolution
Proxy orchestration	No	Yes (--with-proxy-if-needed)
Use case	Programmatic orchestration, multi-agent	Direct harness usage with provider flexibility

6b.1 Syntax

amux launch <harness> [provider] [flags...]

Positional arguments:

Argument	Required	Description
<harness>	Yes	Target harness name. Registered SubprocessAdapter.agent values: claude, codex, gemini, opencode, copilot, cursor, pi, omp, openclaw, hermes, droid, amp, qwen.
[provider]	No	Provider/backend identifier. If omitted, the harness's default native provider is used. See §6b.3 for the full taxonomy.

6b.2 Flags

Provider Configuration

Flag	Short	Type	Description
--model	-m	string	Model identifier (provider-specific format). Required for non-default providers.
--api-key		string	API key for the target provider. Can also be set via provider-specific env vars.
--api-base		string	Custom API base URL. Overrides provider defaults.
--region		string	Cloud region (for Bedrock, Vertex).
--project		string	Cloud project ID (for Vertex, Foundry).
--resource-group		string	Resource group (for Azure/Foundry).
--endpoint-name		string	Named deployment/endpoint (Azure, Foundry, Bedrock).
--transport	-t	string	Wire protocol the harness should speak. One of: anthropic, openai-chat, openai-responses, google. Default: auto-detected from harness and provider.
--profile		string	Named provider profile from ~/.amux/providers.json.
--auth-command		string	External command that emits a bearer token on stdout.

Proxy Control

Flag	Type	Default	Description
--with-proxy-if-needed	boolean	false	Launch amux-proxy automatically if the harness cannot speak the provider's native transport directly.
--with-proxy	boolean	false	Force proxy launch even if the harness supports the provider natively. Useful for observability or logging.
--no-proxy	boolean	false	Explicitly disable proxy. Errors if the harness cannot reach the provider without one.
--proxy-port	number	0 (auto)	Port for the proxy server. 0 = OS-assigned ephemeral port.
--proxy-log-level	string	warn	Log level for the proxy process: debug, info, warn, error.

Session Control

Flag	Short	Type	Description
--resume	-r	string	Resume an existing session by ID or name. Passes the harness-specific resume flag through.
--session-id	-s	string	Explicit session ID for a new session.

Execution Mode

Flag	Short	Type	Description
--prompt	-p	string	Initial prompt. When set, runs in non-interactive mode: sends the prompt, streams output, and exits when the harness exits. When omitted, runs in interactive mode with full stdin/stdout passthrough.
--max-turns		number	Turn limit (non-interactive mode).
--max-budget-usd		number	Cost limit (where the harness supports it).

Harness Passthrough

Flag	Type	Description
--harness-args	string[]	Raw arguments forwarded verbatim to the harness CLI after all amux-managed args. Use the -- separator: amux launch claude api -- --bare --verbose.

General

Flag	Short	Type	Default	Description
--json		boolean	false	Output machine-readable JSON for launch status and proxy lifecycle events. Does not affect raw harness output.
--debug	-d	boolean	false	Debug mode. Logs proxy and harness process details to stderr.
--dry-run		boolean	false	Print the resolved command, env vars, and proxy config as JSON without executing.

6b.3 Supported Provider IDs

Provider ID	Description	Default Transport	Default Auth
anthropic	Anthropic direct API	anthropic	API key
openai	OpenAI direct API	openai-responses	API key
google	Google AI Studio	google	API key
bedrock	AWS Bedrock	anthropic	IAM / AWS profile
vertex	Google Vertex AI	google	ADC / service account
azure	Azure OpenAI	openai-chat	API key / AD token
foundry	Azure AI Foundry	openai-chat	API key / AD token
ollama	Local Ollama instance	openai-chat	None
local	Generic local model server	openai-chat	None
openrouter	OpenRouter	openai-chat	API key
groq	Groq	openai-chat	API key
fireworks	Fireworks AI	openai-chat	API key
together	Together AI	openai-chat	API key
deepseek	DeepSeek	openai-chat	API key
mistral	Mistral AI	openai-chat	API key
cerebras	Cerebras	openai-chat	API key
sambanova	SambaNova	openai-chat	API key
custom	User-defined endpoint	Requires --transport	Any (via flags)

6b.4 Supported Transport IDs

Transport ID	Endpoint	Wire Format	Used By
anthropic	POST /v1/messages	Anthropic Messages API (SSE)	Claude Code
openai-chat	POST /v1/chat/completions	OpenAI Chat Completions	OpenCode, Codex (wire_api=chat)
openai-responses	POST /v1/responses	OpenAI Responses API	Codex (default)
google	POST /v1beta/models/:model:generateContent	Google GenerateContent	Gemini CLI

6b.5 Native Support Matrix

This matrix shows which harness+provider combinations work without a proxy. Use --with-proxy-if-needed for combinations marked with a cross.

	anthropic	bedrock	vertex	azure	foundry	google	openai	ollama
claude	Native	Native	Native	No	Native	No	No	Via ANTHROPIC_BASE_URL
codex	No	No	No	No	No	No	Native	Native (--oss)
gemini	No	No	Native (ADC)	No	No	Native	No	No
opencode	Native	Native (SDK)	Native (SDK)	Native (SDK)	No	Native (SDK)	Native	OpenAI-compat
copilot	No	No	No	No	No	No	No	No
cursor	Native	No	No	No	No	No	No	No

Cells marked "No" require --with-proxy-if-needed. Cells marked "Via ANTHROPIC_BASE_URL" or "OpenAI-compat" work with an env var workaround but a proxy is recommended for reliability.

6b.6 Examples

# Interactive Claude Code with default provider (Anthropic direct)
amux launch claude

# Interactive Claude Code via Bedrock (native, no proxy needed)
amux launch claude bedrock --region us-east-1

# Interactive Claude Code via Vertex (native)
amux launch claude vertex --project my-gcp-project --region us-central1

# Interactive Codex via Bedrock (proxy required: codex speaks OpenAI, bedrock speaks Anthropic)
amux launch codex bedrock --region us-east-1 \
  --model anthropic.claude-sonnet-4-20250514-v1:0 \
  --with-proxy-if-needed

# Non-interactive (one-shot) run via Vertex
amux launch claude vertex --project my-project --region us-central1 \
  -p "Explain the authentication flow in this codebase" \
  --max-turns 3

# Interactive Codex via Ollama (local, no proxy needed with --oss flag)
amux launch codex ollama --model qwen3:32b

# Interactive Claude Code via Ollama (proxy bridges Ollama to Anthropic transport)
amux launch claude ollama --model qwen3:32b --with-proxy-if-needed

# Use a named provider profile from ~/.amux/providers.json
amux launch claude --profile work-bedrock

# Dry run: see what would be executed without running it
amux launch codex bedrock --region us-east-1 --model anthropic.claude-sonnet-4-20250514-v1:0 \
  --with-proxy-if-needed --dry-run

# Passthrough raw harness args after --
amux launch claude api -- --bare --verbose

6b.7 Non-Interactive vs Interactive Mode

Interactive mode (default, no --prompt): stdin, stdout, and stderr are passed through directly to the harness. The user interacts with the harness TUI natively. amux only manages the proxy lifecycle and process signals.

Non-interactive mode (--prompt is set): the prompt is delivered to the harness via its native mechanism (e.g., --print for claude, exec for codex, --prompt for gemini). stdout and stderr are still passed through raw. The process exits when the harness completes its response. Suitable for scripting and CI/CD.

6b.8 Error Codes

Code	Condition
HARNESS_NOT_FOUND	Unknown harness name.
HARNESS_NOT_INSTALLED	Harness binary not found on $PATH.
PROVIDER_UNSUPPORTED	Harness+provider combo has no native support and proxy is not enabled.
PROXY_REQUIRED	Proxy required but --no-proxy is set.
PROXY_LAUNCH_FAILED	amux-proxy failed to start. Check that it is installed: pip install amux-proxy.
AUTH_MISSING	Required provider auth not supplied.

---

7. amux install -- Install Agent CLIs

Install or display installation instructions for agent CLI binaries.

7.1 Syntax

amux install <agent> [flags...]

<agent> is required. Must be one of the ten built-in agent names: claude, codex, gemini, copilot, cursor, opencode, pi, omp, openclaw, hermes.

7.2 Flags

Flag	Short	Type	Default	Description
--dry-run	--	boolean	false	Print the install commands without executing them.
--method	--	string	Auto-detected	Force a specific install method: npm, pip, brew, gh-extension, curl, winget, scoop, manual.
--yes	-y	boolean	false	Non-interactive: execute install commands without confirmation prompts.

7.3 Behavior

1. Resolves the adapter for <agent>.
2. Reads AgentCapabilities.installMethods filtered by the current platform (process.platform).
3. If --method is specified, selects only the matching install method. Exits with code 2 if no method matches.
4. For each matching install method: a. Checks prerequisites (InstallMethod.prerequisiteCheck) if defined. Prints a warning if the prerequisite is not met. b. Prints the install command to stdout. c. Unless --dry-run: prompts for confirmation (unless --yes), then executes the command as a child process, streaming stdout/stderr to the terminal.
5. After installation, runs mux.adapters.detect(agent) to verify the install succeeded and prints the detected version.

7.4 Install Methods per Agent

Agent	Method	Command	Platform	Notes
claude	npm	npm install -g @anthropic-ai/claude-code	all	--
claude	brew	brew install claude-code	darwin	--
codex	npm	npm install -g @openai/codex	all	--
gemini	npm	npm install -g @google/gemini-cli	all	--
copilot	gh-extension	gh extension install github/gh-copilot	all	Requires GitHub CLI (gh). Prerequisite check: gh --version.
cursor	manual	Opens download page	darwin, linux	No headless-only install. Full app required.
cursor	winget	winget install Cursor.Cursor	win32	--
opencode	npm	npm install -g opencode	all	--
opencode	brew	brew install opencode/tap/opencode	darwin	--
pi	npm	npm install -g @mariozechner/pi-coding-agent	all	--
omp	npm	npm install -g @oh-my-pi/pi-coding-agent	all	--
openclaw	npm	npm install -g openclaw	all	Requires Node 22.16+, 16GB RAM minimum.
hermes	pip	pip install hermes-agent	all	Requires Python >= 3.11. Alternative: uv pip install hermes-agent.

7.5 API Mapping

CLI	SDK
amux install claude	mux.adapters.installInstructions('claude', process.platform)
amux install --dry-run gemini	mux.adapters.installInstructions('gemini', process.platform) (display only)

7.6 Examples

# Install Claude Code
amux install claude

# See what would be installed without running
amux install --dry-run gemini

# Force npm method
amux install opencode --method npm

# Non-interactive install
amux install codex --yes

# Install hermes (Python agent)
amux install hermes

---

8. amux adapters -- Adapter Discovery

List and inspect registered adapters and their installation state.

8.1 Syntax

amux adapters list [flags...]
amux adapters detect <agent> [flags...]

8.2 amux adapters list

Lists all registered adapters with their installation status, version, and authentication state.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON array.

Output columns (human mode):

Column	Description
Agent	Agent name.
Installed	yes / no.
Version	Detected version string, or -- if not installed.
Auth	authenticated, unauthenticated, expired, unknown, or --.
Path	Absolute path to CLI binary, or --.

API mapping: mux.adapters.list() combined with mux.adapters.installed() for the installed/version/auth columns.

8.3 amux adapters detect <agent>

Detect a single agent: checks installation, resolves the binary path, detects the version, and checks authentication state.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON object.

Output (human mode): Key-value pairs:

Agent:     claude
Installed: yes
Path:      /usr/local/bin/claude
Version:   1.2.3
Min version: 1.0.0
Meets min:  yes
Auth:      authenticated
Model:     claude-sonnet-4-20250514

API mapping: mux.adapters.detect('claude') returns InstalledAgentInfo.

8.4 Error Behavior

• Unknown agent name: exit code 3 (AGENT_NOT_FOUND).
• Agent not installed (for detect): prints the detection result showing installed: false, exits with code 0 (detection succeeded; the result is "not installed").

---

9. amux capabilities -- Agent Capabilities

Display the capabilities manifest for an agent, optionally scoped to a specific model.

9.1 Syntax

amux capabilities <agent> [flags...]

9.2 Flags

Flag	Type	Default	Description
--model	string	--	Show model-level capabilities for a specific model ID.
--json	boolean	false	Output as JSON object.

9.3 Behavior

• Without --model: prints agent-level capabilities (AgentCapabilities) as defined in 06-capabilities-and-models.md, Section 2.
• With --model: prints the union of agent-level and model-level capabilities (ModelCapabilities) for the specified model.

Output (human mode): Grouped key-value display organized by category (session, streaming, tool calling, thinking, output, skills, plugins, process, auth, install).

API mapping:

CLI	SDK
amux capabilities claude	mux.adapters.capabilities('claude')
amux capabilities claude --model claude-sonnet-4-20250514	mux.adapters.capabilities('claude') + mux.models.model('claude', 'claude-sonnet-4-20250514')

9.4 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown model (with --model): exit code 1, error message listing available models.

---

10. amux models -- Model Registry

List, inspect, and refresh model metadata for agents.

10.1 Syntax

amux models list <agent> [flags...]
amux models get <agent> <model-id> [flags...]
amux models refresh <agent> [flags...]
amux models current <agent> [flags...]
amux models set <agent> <model-id> [--provider <provider>] [flags...]

10.2 amux models list <agent>

List all models available for an agent.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON array.

Output columns (human mode):

Column	Description
Model ID	The model identifier string.
Display Name	Human-readable name.
Provider	Normalized provider family (anthropic, openai, configurable, etc.).
Protocol	Normalized request protocol (messages, responses, chat, custom).
Deploy	Typical deployment path (hosted, local, gateway, hybrid).
Context Window	Maximum context in tokens.
Source	bundled or remote.
Default	Whether this is the adapter's default model.

API mapping: mux.models.catalog('claude') returns the per-adapter model catalog with default-entry metadata.

10.3 amux models get <agent> <model-id>

Show detailed capabilities for a single model.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON object.

Output (human mode): Key-value display showing all ModelCapabilities fields.

API mapping: mux.models.model('claude', 'claude-sonnet-4-20250514') returns ModelCapabilities | null.

10.4 amux models refresh <agent>

Refresh the model list from the agent's remote source (where applicable).

API mapping: mux.models.refresh('claude').

10.5 amux models current <agent>

Show the configured model, adapter default, and effective model selection for an agent.

API mapping: mux.config.getModelSelection('claude') plus mux.models.model(...) for effective-model details.

10.6 amux models set <agent> <model-id>

Validate and persist the configured model for an agent. Optional --provider records the selected provider for configurable/local-provider adapters.

API mapping: mux.models.validate('claude', 'sonnet') followed by mux.config.setModelSelection('claude', { model, provider }).

10.7 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown model (for get): exit code 1, error message listing available models.

---

11. amux plugin -- Native Plugin Management

Unified interface for managing native agent plugins through CLI delegation. Commands delegate to each agent's native plugin system (e.g., claude plugins, copilot plugin, gemini extensions). All subcommands are capability-gated: invoking on an agent where native plugin CLI commands don't exist produces exit code 6 (CAPABILITY_ERROR).

11.1 Syntax

amux plugin list <agent> [flags...]
amux plugin install <agent> <plugin-id> [flags...]
amux plugin uninstall <agent> <plugin-id> [flags...]
amux plugin update <agent> <plugin-id> [flags...]
amux plugin marketplace <agent> [subcommand] [flags...]

11.2 amux plugin list <agent>

List installed plugins for an agent via native CLI.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON array.

API mapping: Delegates to agent's native command (e.g., claude plugins list).

11.3 amux plugin install <agent> <plugin-id>

Install a plugin via agent's native CLI.

Flags:

Flag	Short	Type	Default	Description
--yes	-y	boolean	false	Skip confirmation prompt.

API mapping: Delegates to agent's native install command.

11.4 amux plugin uninstall <agent> <plugin-id>

Uninstall a plugin via agent's native CLI.

Flags:

Flag	Short	Type	Default	Description
--yes	-y	boolean	false	Skip confirmation prompt.

API mapping: Delegates to agent's native uninstall command.

11.5 amux plugin update <agent> <plugin-id>

Update a plugin via agent's native CLI.

API mapping: Delegates to agent's native update command.

11.6 amux plugin marketplace <agent> [subcommand]

Access agent's native plugin marketplace commands.

API mapping: Delegates to agent's marketplace commands (e.g., claude plugins marketplace).

11.7 Plugin Support per Agent

Agent	Native Plugin Support	CLI Command
Claude	✅ Full marketplace	claude plugins
Gemini	✅ Extensions	gemini extensions
Codex	✅ Plugin directory	codex plugins
Copilot	✅ Plugin marketplace	copilot plugin
OpenCode	✅ Three-tier system	opencode plugins
Cursor	❌ Hook-only (see Section 12)	N/A
All others	❌ MCP-only (see Section 12)	N/A

11.8 Examples

# List installed plugins via native CLI
amux plugin list claude
amux plugin list gemini

# Install plugins via native marketplace
amux plugin install claude @anthropic/frontend-design
amux plugin install copilot github/copilot-agent

# Access native marketplace
amux plugin marketplace claude
amux plugin marketplace copilot

---

12. amux mcp -- MCP Server Management

Unified interface for managing Model Context Protocol servers across all agents. MCP servers provide cross-agent capabilities and integrations. All agents support MCP servers.

12.1 Syntax

amux mcp list <agent> [flags...]
amux mcp install <agent> <mcp-server> [flags...]
amux mcp uninstall <agent> <mcp-server> [flags...]

12.2 amux mcp list <agent>

List installed MCP servers for an agent.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON array.
--project	boolean	false	List project-specific MCP servers only.

Output columns (human mode):

Column	Description
Server Name	MCP server identifier.
Status	enabled / disabled.
Command	Executable command.
Scope	global / project.

12.3 amux mcp install <agent> <mcp-server>

Install an MCP server for an agent.

Flags:

Flag	Short	Type	Default	Description
--project	-p	boolean	false	Install to project scope (vs. global).
--yes	-y	boolean	false	Skip confirmation prompt.

12.4 amux mcp uninstall <agent> <mcp-server>

Uninstall an MCP server from an agent.

Flags:

Flag	Short	Type	Default	Description
--yes	-y	boolean	false	Skip confirmation prompt.

12.5 MCP Server Registry

All MCP servers are available from the official registry at https://modelcontextprotocol.io.

12.6 Examples

# List MCP servers for an agent
amux mcp list claude
amux mcp list cursor

# Install MCP server globally
amux mcp install claude filesystem
amux mcp install gemini postgres

# Install MCP server to project
amux mcp install claude web-browser --project

# Remove MCP server
amux mcp uninstall claude filesystem

---

13. amux sessions -- Session Management

Read-only access to agent session data. The CLI delegates to SessionManager (see 07-session-manager.md, Section 2). Session data is never modified by these commands.

12.1 Syntax

amux sessions list <agent> [flags...]
amux sessions show <agent> <session-id> [flags...]
amux sessions search <query> [flags...]
amux sessions export <agent> <session-id> [flags...]
amux sessions diff <agent>:<id> <agent>:<id> [flags...]
amux sessions resume <agent> <session-id> [flags...]
amux sessions fork <agent> <session-id> [flags...]

12.2 amux sessions list <agent>

List sessions for an agent.

Flags:

Flag	Type	Default	Description
--since	string	--	ISO 8601 date or relative (e.g., 2024-01-01, 7d, 1w). Include sessions after this time.
--until	string	--	ISO 8601 date or relative. Include sessions before this time.
--model	string	--	Filter by model ID.
--tag	string	--	Filter by run tag (from run-index.jsonl). Repeatable.
--limit	number	50	Maximum number of sessions to return.
--sort	string	date	Sort order: date, cost, turns.
--json	boolean	false	Output as JSON array.

Output columns (human mode):

Column	Description
Session ID	Native session identifier.
Model	Model ID used.
Turns	Number of conversation turns.
Cost	Total cost in USD.
Date	Session start date.
Summary	First line of the prompt (truncated).

API mapping: mux.sessions.list('claude', { since, until, model, tags, limit, sort }) returns SessionSummary[].

12.3 amux sessions show <agent> <session-id>

Display the full content of a session.

Flags:

Flag	Type	Default	Description
--format	string	markdown	Output format: json, jsonl, markdown.

API mapping: mux.sessions.export('claude', 'abc123', 'markdown').

12.4 amux sessions tail <agent> [session-id]

This command is not part of the current public CLI surface.

@a5c-ai/agent-mux-core does not currently expose a truthful live session-watch API. Earlier drafts described mux.sessions.watch(), but that contract was removed rather than shipping synthetic AgentEvent payloads derived from arbitrary session-file changes.

12.5 amux sessions search <query>

Full-text search across sessions.

Flags:

Flag	Type	Default	Description
--agent	AgentName	All	Restrict search to a specific agent.
--since	string	--	Search sessions after this time.
--until	string	--	Search sessions before this time.
--json	boolean	false	Output as JSON array.

API mapping: mux.sessions.search({ text: query, agent, since, until }) returns SessionSummary[].

12.6 amux sessions export <agent> <session-id>

Export a session to a file or stdout.

Flags:

Flag	Type	Default	Description
--format	string	json	Export format: json, jsonl, markdown.

Output: The exported session content is written to stdout. Redirect to a file as needed.

API mapping: mux.sessions.export('claude', 'abc123', 'json') returns string.

12.7 amux sessions diff <agent>:<id> <agent>:<id>

Compute a structural diff between two sessions. Sessions may belong to the same or different agents.

Syntax: Each argument uses the unified ID format <agent>:<native-session-id>.

amux sessions diff claude:abc123 claude:def456
amux sessions diff claude:abc123 gemini:xyz789

API mapping: mux.sessions.diff({ agent: 'claude', sessionId: 'abc123' }, { agent: 'gemini', sessionId: 'xyz789' }) returns SessionDiff.

12.8 amux sessions resume <agent> <session-id>

Resume a session by starting a new interactive run that continues from the specified session.

Behavior: Equivalent to amux run <agent> --session <session-id> --interactive. Enters REPL mode (see Section 13).

API mapping: mux.run({ agent, sessionId, ... }) with interactive REPL loop.

12.9 amux sessions fork <agent> <session-id>

Fork a session and enter an interactive run on the new branch.

Behavior: Equivalent to amux run <agent> --fork <session-id> --interactive. Enters REPL mode.

API mapping: mux.run({ agent, forkSessionId: sessionId, ... }) with interactive REPL loop.

12.10 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown session ID: exit code 8 (SESSION_NOT_FOUND).
• Corrupt session file: exit code 1 (PARSE_ERROR), with diagnostic message to stderr.

---

13. Interactive REPL Mode (amux run -i)

When --interactive / -i is set on amux run, the CLI enters a Read-Eval-Print Loop for multi-turn conversation with the agent.

13.1 Entry Conditions

REPL mode is entered when:

• amux run -i is invoked (with or without an initial prompt).
• amux sessions resume is invoked.
• amux sessions fork is invoked.

13.2 REPL Behavior

1. If an initial prompt is provided, it is sent as the first turn.
2. After the agent completes its response, the CLI prints a prompt indicator (for example, amux>) and waits for user input on stdin.
3. User input is sent to the running agent via RunHandle.continue(prompt).
4. Tool approval requests are handled inline: the CLI prints the request and prompts for [y]es / [n]o / [a]lways on stderr.
5. The loop continues until:
   • The user types /exit or /quit.
   • The user presses Ctrl+D (EOF on stdin).
   • The user presses Ctrl+C twice within 1 second.
   • The agent terminates.

13.3 REPL Commands

The following slash commands are recognized within the REPL:

Command	Description
/exit, /quit	End the session and exit.
/abort	Abort the current agent operation.
/interrupt	Send interrupt (SIGINT) to the agent.
/pause	Pause agent execution.
/resume	Resume paused execution.
/status	Print current run state, session ID, model, and cost.
/cost	Print accumulated cost for this run.
/session	Print the current session ID.
/help	Print REPL command reference.

SDK frontends built on the same live-run surface can also defer follow-up prompts with RunHandle.queue() and RunHandle.steer(). The bundled TUI maps /queue ..., /steer ..., and /steer-tool ... onto those APIs when a run is already active.

13.4 REPL + JSONL

When -i and --json are combined, the REPL reads prompts from stdin (one per line) and emits JSONL events to stdout. This enables programmatic multi-turn conversation. The REPL terminates on stdin EOF.

---

14. Pipe and Stdin Support

The CLI supports pipe-based workflows for composability with Unix tools.

14.1 Reading Prompt from Stdin

When amux run is invoked without a prompt argument and stdin is not a TTY, the entire stdin is read and used as the prompt:

echo "refactor this function" | amux run claude
cat prompt.txt | amux run gemini --json
git diff | amux run codex "review this diff"

When both a positional prompt and stdin are provided, the positional prompt takes precedence and stdin is ignored.

14.2 JSONL Output for Piping

JSONL output (--json) is designed for consumption by downstream tools:

# Extract only text deltas
amux run claude "explain X" --json | jq 'select(.type == "text_delta") | .delta'

# Monitor tool calls
amux run codex "fix tests" --json | jq 'select(.type | startswith("tool_"))'

# Extract final text
amux run gemini "summarize" --json | jq 'select(.type == "run_result") | .text'

14.3 TTY Detection

The CLI detects whether stdin and stdout are TTYs using process.stdin.isTTY and process.stdout.isTTY:

stdin	stdout	Behavior
TTY	TTY	Full interactive mode: colors, spinners, approval prompts.
TTY	Pipe	Colors disabled, spinners disabled, approval prompts still on stderr.
Pipe	TTY	Prompt read from stdin pipe. Approval prompts on stderr.
Pipe	Pipe	Full non-interactive: --json implied if not set, approvals auto-denied.

---

15. amux cost -- Cost Reporting

Aggregate and display cost data across runs.

15.1 Syntax

amux cost report [flags...]

15.2 Flags

Flag	Type	Default	Description
--agent	AgentName	All	Filter by agent. Repeatable.
--since	string	--	Include runs after this time. ISO 8601 or relative.
--until	string	--	Include runs before this time.
--model	string	--	Filter by model.
--tag	string	--	Filter by tag. Repeatable.
--group-by	string	agent	Group results: agent, model, day, tag.
--json	boolean	false	Output as JSON object.

15.3 Output (Human Mode)

A formatted table showing cost breakdowns per grouping:

Cost Report (last 30 days)
──────────────────────────────────────────
Agent       Runs    Input$    Output$    Total
claude        42    $1.23      $3.45     $4.68
codex         15    $0.50      $1.20     $1.70
gemini         8    $0.10      $0.30     $0.40
──────────────────────────────────────────
Total         65    $1.83      $4.95     $6.78

15.4 API Mapping

CLI	SDK
amux cost report --agent claude --since 30d	mux.sessions.totalCost({ agent: 'claude', since: '30d' })
amux cost report --group-by model	mux.sessions.totalCost({ groupBy: 'model' })

---

16. amux config -- Configuration Management

Read, write, and validate agent configuration files through the unified ConfigManager interface. See 08-config-and-auth.md, Section 2 for the full ConfigManager specification.

16.1 Syntax

amux config get <agent> [field] [--scope global|project] [--json]
amux config set <agent> <field> <value> [--scope global|project]
amux config schema <agent> [--json]
amux config validate <agent> [--json]
amux config mcp list <agent> [--json]
amux config mcp add <agent> [--scope global|project]
amux config mcp remove <agent> <server-name> [--scope global|project]
amux config reload [agent]

Common Config Flags

Flag	Type	Default	Description
--scope	global | project	merged	Target a specific config file scope. global reads/writes only ~/.agent-mux/config.json (or the agent's global config). project reads/writes only .agent-mux/config.json (or the agent's project config). When omitted, read commands return the merged result (project overrides global); write commands target the global file.
--json	flag	off	Output in JSON format (single object, not JSONL). Applies to all read/query subcommands.

16.2 amux config get <agent> [field]

Read configuration for an agent. If field is omitted, prints the full merged config. If field is provided (dot-notation), prints only that field's value.

API mapping:

CLI	SDK
amux config get claude	mux.config.get('claude')
amux config get claude model	mux.config.getField('claude', 'model')
amux config get claude permissions.allow	mux.config.getField('claude', 'permissions.allow')

16.3 amux config set <agent> <field> <value>

Write a single field to the agent's native config file.

<value> is parsed as JSON if it starts with {, [, ", or is a number/boolean literal. Otherwise it is treated as a plain string.

API mapping: mux.config.setField('claude', 'model', 'claude-sonnet-4-20250514').

Error behavior:

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Invalid field/value: exit code 2 (VALIDATION_ERROR).
• File write failure: exit code 7 (CONFIG_ERROR).
• Lock contention: exit code 7 (CONFIG_LOCK_ERROR), message indicates retry.

16.4 amux config schema <agent>

Print the configuration schema for an agent, showing all recognized fields, their types, defaults, and valid ranges.

API mapping: mux.config.schema('claude') returns AgentConfigSchema.

16.5 amux config validate <agent>

Validate the current config file(s) for an agent against the schema. Prints validation results: field-level errors and warnings.

API mapping: mux.config.validate('claude', mux.config.get('claude')) returns ValidationResult.

16.6 amux config mcp list <agent>

List MCP servers configured for an agent.

API mapping: mux.config.getMcpServers('claude') returns McpServerConfig[].

16.7 amux config mcp add <agent>

Add an MCP server to the agent's config. The CLI prompts for server name, command, args, and environment variables interactively. In non-interactive mode (piped stdin), reads a JSON McpServerConfig from stdin.

API mapping: mux.config.addMcpServer('claude', serverConfig).

Error behavior:

• Agent does not support MCP: exit code 6 (CAPABILITY_ERROR).
• Server name already exists: exit code 7 (CONFIG_ERROR).

16.8 amux config mcp remove <agent> <server-name>

Remove an MCP server from the agent's config by name.

API mapping: mux.config.removeMcpServer('claude', 'my-server').

16.9 amux config reload [agent]

Spec-level addition: This command is not in the scope document's CLI listing (scope §21) but is specified in 08-config-and-auth.md Section 2 and Section 15.1. It maps to the ConfigManager.reload() method added by that spec.

Invalidate the config cache and re-read from disk. If agent is omitted, reloads all agents.

This is useful when external processes (the agent's own CLI, manual editing) have modified config files since the last read.

API mapping: mux.config.reload('claude') or mux.config.reload().

16.10 Examples

# Read full config
amux config get claude

# Read single field
amux config get claude model

# Set a field
amux config set claude model claude-sonnet-4-20250514

# View schema
amux config schema codex

# Validate current config
amux config validate gemini

# List MCP servers
amux config mcp list claude

# Remove an MCP server
amux config mcp remove claude my-custom-server

# Reload after external edit
amux config reload claude

---

17. amux profiles -- Profile Management

Manage named RunOptions presets. Profiles are stored as JSON files in ~/.agent-mux/profiles/ (global) or .agent-mux/profiles/ (project). See 02-run-options-and-profiles.md, Section 10 for the full ProfileManager specification.

17.1 Syntax

amux profiles list [flags...]
amux profiles show <name>
amux profiles set <name> [run-flags...]
amux profiles delete <name> [flags...]
amux profiles apply <name>

17.2 amux profiles list

List all available profiles from both global and project directories.

Flags:

Flag	Type	Default	Description
--scope	string	All	Filter by scope: global, project.
--json	boolean	false	Output as JSON array.

Output columns (human mode):

Column	Description
Name	Profile name.
Scope	global or project.
Agent	Default agent in profile, or --.
Model	Default model in profile, or --.

API mapping: mux.profiles.list({ scope }) returns ProfileEntry[].

17.3 amux profiles show <name>

Display the resolved contents of a profile (merged global + project).

API mapping: mux.profiles.show(name) returns ResolvedProfile.

17.4 amux profiles set <name> [run-flags...]

Create or update a profile. The profile data is derived from the provided run flags. Any flag accepted by amux run (except per-run ephemeral flags) can be used.

Per-run ephemeral flags that are rejected (per 02-run-options-and-profiles.md, Section 10.3):

--cwd, --env, --run-id, --attach, --fork, --no-session, --project-id, --interactive, --quiet.

Note: --system and --system-mode are NOT rejected — systemPrompt and systemPromptMode are valid profile fields (spec 02 §10.2).

These flags correspond to RunOptions fields that are per-run ephemeral and excluded from profile storage: cwd, env, runId, attachments, systemPrompt, systemPromptMode, forkSessionId, noSession, projectId, plus CLI-only flags --interactive and --quiet.

Flags:

Flag	Type	Default	Description
--scope	string	Auto	Target scope: global or project. Defaults to project if a project directory exists, otherwise global.

API mapping: mux.profiles.set(name, profileData, { scope }).

Examples:

# Create a "fast" profile
amux profiles set fast --agent claude --model claude-sonnet-4-20250514 --yolo --max-turns 5

# Create a "careful" profile
amux profiles set careful --agent claude --thinking-effort high --deny

# Create global profile
amux profiles set shared-fast --scope global --agent gemini --max-tokens 4096

17.5 amux profiles delete <name>

Delete a profile.

Flags:

Flag	Type	Default	Description
--scope	string	Both	Scope to delete from: global, project. If omitted, deletes from both.

API mapping: mux.profiles.delete(name, { scope }).

17.6 amux profiles apply <name>

Resolve a profile and print the resulting RunOptions values. Does not start a run. Useful for previewing what a profile produces.

API mapping: mux.profiles.apply(name) returns Partial<RunOptions>.

17.7 Error Behavior

• Unknown profile: exit code 9 (PROFILE_NOT_FOUND).
• Invalid profile data: exit code 2 (VALIDATION_ERROR).

---

18. amux auth -- Authentication

Check and guide authentication state for agents. The CLI never writes credentials or modifies auth state -- it only inspects and provides guidance.

18.1 Syntax

amux auth check [agent]
amux auth setup <agent>

18.2 amux auth check [agent]

Check authentication state. If agent is omitted, checks all agents.

Flags:

Flag	Type	Default	Description
--json	boolean	false	Output as JSON.

Output (human mode, single agent):

Agent:    claude
Status:   authenticated
Method:   api-key
Identity: user@example.com
Checked:  2025-01-15T10:30:00Z

Output (human mode, all agents):

Agent	Status	Method	Identity
claude	authenticated	api-key	user@...
codex	unauthenticated	--	--
gemini	authenticated	oauth	user@...
...	...	...	...

API mapping:

CLI	SDK
amux auth check claude	mux.auth.check('claude') returns AuthState
amux auth check	mux.auth.checkAll() returns Record<AgentName, AuthState>

18.3 amux auth setup <agent>

Print setup guidance for authenticating with an agent. Does not perform authentication itself.

Output: Structured guidance including:

• Required steps (numbered list).
• Environment variables to set.
• Commands to run.
• Documentation links.
• Platform-specific notes.

API mapping: mux.auth.getSetupGuidance('claude') returns AuthSetupGuidance.

18.4 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• auth check with unauthenticated result: exits with code 0 (the check succeeded; the result is "unauthenticated"). The status is reported in the output.

---

18b. amux skill -- Skill Management

File-convention only (no native harness command). Skills are folders containing a SKILL.md plus assets, installed under per-harness conventions.

amux skill list <agent> [--global|--project]
amux skill add <agent> <source-folder> [--name <n>] [--force] [--global|--project]
amux skill remove <agent> <name> [--global|--project]
amux skill where <agent>
amux skill agents           # list supported harnesses

Supported harnesses: claude, codex, cursor, opencode, gemini, copilot. Paths: $HOME/.<agent>/skills/ (global) or <cwd>/.<agent>/skills/ (project).

---

18c. amux agent -- Sub-agent Management

File-convention only. Copies agent definition files (markdown/yaml/json) into per-harness sub-agent directories.

amux agent list <agent> [--global|--project]
amux agent add <agent> <source> [--name <n>] [--force] [--global|--project]
amux agent remove <agent> <name> [--global|--project]
amux agent where <agent>
amux agent agents           # list supported harnesses

Supported: claude, claude-code, codex, cursor, opencode. Paths: $HOME/.<agent>/agents/ (global) or <cwd>/.<agent>/agents/ (project).

References:

• Claude: https://code.claude.com/docs/en/sub-agents
• Codex: https://developers.openai.com/codex/subagents#custom-agents

---

18d. amux hooks -- Hook Management

Manage hook registrations and dispatch. Backed by HookConfigManager in core.

amux hooks <agent> discover                      # native hook types
amux hooks <agent> list
amux hooks <agent> add <hookType> [--handler builtin|command|script] [--target <t>] [--id <id>] [--global]
amux hooks <agent> remove <id> [--global]
amux hooks <agent> set <id> [--priority N] [--enabled true|false] [--target <t>]
amux hooks <agent> handle <hookType>             # stdin JSON → dispatch → result

Storage: $HOME/.amux/hooks.json (global), <cwd>/.amux/hooks.json (project).

---

19. amux init -- Project Initialization

Create the .agent-mux/ directory in the current working directory with default configuration.

19.1 Syntax

amux init [flags...]

19.2 Behavior

1. Creates .agent-mux/ in the current directory (or the directory specified by --project-dir).
2. Creates .agent-mux/config.json with an empty object {}.
3. Creates .agent-mux/profiles/ directory.
4. Prints confirmation to stdout.
5. If .agent-mux/ already exists, prints a message and exits with code 0 (idempotent).

19.3 Flags

Flag	Type	Default	Description
--json	boolean	false	Output result as JSON.

---

20. Signal Handling

The CLI handles process signals for graceful shutdown and run control.

20.1 Unix (macOS, Linux)

Signal	Behavior
SIGINT (Ctrl+C)	First: sends interrupt() to the active RunHandle. The agent may handle this gracefully (stop current tool call, remain alive). Second within 1 second: sends abort() to force shutdown. Third or if no active run: exits immediately.
SIGTERM	Initiates graceful shutdown: sends SIGINT to all child processes, waits the grace period (default 5000ms), then sends SIGKILL to any remaining children. Exits with code 13 (ABORTED).
SIGKILL	Cannot be caught. OS terminates the process. Child processes receive SIGKILL via process group.
SIGTSTP (Ctrl+Z)	Sends pause() to the active RunHandle.
SIGCONT	Sends resume() to the active RunHandle.

20.2 Windows

Windows does not have POSIX signals. The CLI uses alternative mechanisms:

Event	Behavior
Ctrl+C	Handled via process.on('SIGINT') (Node.js emulation). Behavior matches Unix SIGINT above.
Ctrl+Break	Sends abort() to the active RunHandle. Equivalent to double-SIGINT on Unix.
Console close / SIGTERM	process.on('SIGTERM') triggers graceful shutdown. Child processes are terminated via TerminateProcess Win32 API after the grace period.
SIGTSTP / SIGCONT	Not available on Windows. Pause/resume is only available through REPL commands (/pause, /resume).

20.3 Zombie Prevention

All spawned child processes are registered in a cleanup list. On Node.js beforeExit and exit events, the CLI sends SIGKILL (Unix) or TerminateProcess (Windows) to any still-running children. This prevents zombie processes.

The grace period for graceful shutdown is configurable via AGENT_MUX_GRACE_PERIOD_MS environment variable (default: 5000ms).

---

21. Environment Variables

The following environment variables are recognized by the CLI. CLI flags take precedence over environment variables.

Variable	Type	Default	Description	Equivalent Flag
AGENT_MUX_CONFIG_DIR	string	~/.agent-mux/	Override global config directory.	--config-dir
AGENT_MUX_PROJECT_DIR	string	.agent-mux/	Override project config directory.	--project-dir
AGENT_MUX_DEFAULT_AGENT	AgentName	--	Default agent when none is specified.	--agent (global)
AGENT_MUX_GRACE_PERIOD_MS	number	5000	Grace period in milliseconds before SIGKILL on shutdown.	--
NO_COLOR	any	--	Disable colored output when set to any non-empty value. See no-color.org.	--no-color
DEBUG	string	--	When set to amux or amux:*, enables debug logging to stderr.	--debug
FORCE_COLOR	any	--	Force colored output even when stdout is not a TTY. Overridden by NO_COLOR and --no-color.	--

21.1 Resolution Order

For any configuration value, the resolution order is (highest precedence first):

1. CLI flags (e.g., --config-dir).
2. Environment variables (e.g., AGENT_MUX_CONFIG_DIR).
3. Project config file (.agent-mux/config.json).
4. Global config file (~/.agent-mux/config.json).
5. Adapter defaults.

This mirrors the SDK resolution order defined in 01-core-types-and-client.md, Section 4.1.1 and 02-run-options-and-profiles.md, Section 7.

---

22. Shell Completion

The CLI provides shell completion scripts for interactive use.

22.1 Generating Completion Scripts

# Bash
amux --completions bash > ~/.local/share/bash-completion/completions/amux
# or
amux --completions bash >> ~/.bashrc

# Zsh
amux --completions zsh > ~/.zfunc/_amux
# or add to .zshrc: fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit

# Fish
amux --completions fish > ~/.config/fish/completions/amux.fish

# PowerShell
amux --completions powershell >> $PROFILE

22.2 Completion Scope

Completions are provided for:

• Top-level commands (run, install, adapters, capabilities, models, plugin, mcp, sessions, cost, config, profiles, auth, init).
• Subcommands (e.g., plugin list, mcp install, config mcp add).
• Flag names and their valid values (e.g., --agent completes to registered agent names, --thinking-effort completes to low, medium, high, max).
• Agent names (positional argument for many commands).
• Model IDs (for --model flag, dynamically queried from the model registry).
• Profile names (for --profile flag).

---

23. Error Output Format

23.1 Human-Readable Errors

In human mode, errors are printed to stderr with the following format:

error: <message>
  code: <ErrorCode>
  agent: <agent> (when applicable)
  hint: <actionable guidance> (when available)

Example:

error: Agent 'cursor' does not support native plugin CLI commands
  code: CAPABILITY_ERROR
  agent: cursor
  hint: Agents with native plugin CLI: claude, gemini, codex, copilot, opencode

23.2 JSON Errors

In JSON mode (--json), errors are emitted as a JSON object to stdout:

{
  "ok": false,
  "error": {
    "code": "CAPABILITY_ERROR",
    "message": "Agent 'cursor' does not support native plugin CLI commands",
    "agent": "cursor",
    "recoverable": false
  }
}

23.3 JSONL Run Errors

During amux run --json, errors appear as typed events in the JSONL stream:

{"type":"error","runId":"01J...","agent":"claude","timestamp":1718000000000,"code":"AUTH_ERROR","message":"Authentication required","recoverable":false}

The type field matches the error event types defined in 04-agent-events.md: auth_error, rate_limit_error, context_exceeded, crash, error.

23.4 Canonical Error Codes

All error codes used by the CLI are defined in 01-core-types-and-client.md, Section 3.1:

Error Code	Description
CAPABILITY_ERROR	Agent/model lacks required capability.
VALIDATION_ERROR	Input fails schema or range validation.
AUTH_ERROR	Authentication required but not configured.
AGENT_NOT_FOUND	No adapter registered for the agent name.
AGENT_NOT_INSTALLED	Adapter exists but CLI binary not on $PATH.
AGENT_CRASH	Agent subprocess terminated unexpectedly.
SPAWN_ERROR	Failed to spawn agent subprocess.
TIMEOUT	Run exceeded wall-clock timeout.
INACTIVITY_TIMEOUT	Run exceeded inactivity timeout.
PARSE_ERROR	Failed to parse agent output or file.
CONFIG_ERROR	Config file read/write/parse failure.
CONFIG_LOCK_ERROR	Advisory file lock acquisition failed.
SESSION_NOT_FOUND	Specified session does not exist.
PROFILE_NOT_FOUND	Specified profile does not exist.
PLUGIN_ERROR	Plugin operation failed.
RATE_LIMITED	Agent reported rate limiting.
CONTEXT_EXCEEDED	Agent's context window exceeded.
ABORTED	Run was aborted by user.
INTERNAL	Internal error in agent-mux.

---

24. Platform-Specific Notes

24.1 Windows

• Signal handling: Windows lacks POSIX signals. See Section 20.2 for the alternative mechanisms used.
• TTY detection: process.stdin.isTTY and process.stdout.isTTY work correctly on Windows terminals (cmd.exe, PowerShell, Windows Terminal). ConPTY is used for PTY-based agents.
• PTY support: node-pty uses ConPTY on Windows 10 1809+ for agents requiring PTY (OpenClaw, some interactive modes).
• Path handling: All internal paths use forward slashes. CLI output uses the platform-native separator. Config file paths (--config-dir, --project-dir) accept both forward and backslashes on Windows.
• Color support: ANSI color codes are supported in Windows Terminal and PowerShell 7+. Legacy cmd.exe may not render colors correctly; --no-color is recommended in that environment.
• Hermes on Windows: Hermes requires WSL2 on Windows. The hermes adapter detects whether WSL2 is available and spawns hermes through wsl when running on native Windows. If WSL2 is not detected, the adapter reports installed: false with guidance to install WSL2.
• omp on Windows: omp has partial Windows support (see agent-mux-scope.md, Section 23). Some features may not work correctly on Windows.
• Shell completion: PowerShell completion is supported via Register-ArgumentCompleter. See Section 22.1.

24.2 macOS

• Homebrew: Several agents offer Homebrew install methods (claude, opencode). The amux install command prefers Homebrew on macOS when available.
• Config paths: Global config at ~/ ($HOME, typically /Users/<user>/).

24.3 Linux

• XDG compliance: Some agents store config in XDG-compliant locations (e.g., ~/.config/ for Gemini, Copilot, OpenCode). The adapters handle this transparently.
• Config paths: Global config at ~/ ($HOME, typically /home/<user>/).

---

25. Command Summary

Quick reference of all commands and their SDK method mappings.

Command	Subcommand	SDK Method
amux run	--	mux.run()
amux install	--	mux.adapters.installInstructions()
amux adapters	list	mux.adapters.list() + mux.adapters.installed()
amux adapters	detect	mux.adapters.detect()
amux capabilities	--	mux.adapters.capabilities() + mux.models.model()
amux models	list	mux.models.catalog()
amux models	get	mux.models.model()
amux models	refresh	mux.models.refresh()
amux models	current	mux.config.getModelSelection() + mux.models.model()
amux models	set	mux.models.validate() + mux.config.setModelSelection()
amux plugin	list	Native CLI delegation
amux plugin	install	Native CLI delegation
amux plugin	uninstall	Native CLI delegation
amux plugin	update	Native CLI delegation
amux plugin	marketplace	Native CLI delegation
amux mcp	list	mux.mcp.list()
amux mcp	install	mux.mcp.install()
amux mcp	uninstall	mux.mcp.uninstall()
amux sessions	list	mux.sessions.list()
amux sessions	show	mux.sessions.export()
amux sessions	search	mux.sessions.search()
amux sessions	export	mux.sessions.export()
amux sessions	diff	mux.sessions.diff()
amux sessions	resume	mux.run({ sessionId })
amux sessions	fork	mux.run({ forkSessionId })
amux cost	report	mux.sessions.totalCost()
amux config	get	mux.config.get() / mux.config.getField()
amux config	set	mux.config.setField()
amux config	schema	mux.config.schema()
amux config	validate	mux.config.validate()
amux config	mcp list	mux.config.getMcpServers()
amux config	mcp add	mux.config.addMcpServer()
amux config	mcp remove	mux.config.removeMcpServer()
amux config	reload	mux.config.reload()
amux profiles	list	mux.profiles.list()
amux profiles	show	mux.profiles.show()
amux profiles	set	mux.profiles.set()
amux profiles	delete	mux.profiles.delete()
amux profiles	apply	mux.profiles.apply()
amux auth	check	mux.auth.check() / mux.auth.checkAll()
amux auth	setup	mux.auth.getSetupGuidance()
amux skill	list / add / remove / where / agents	File-convention (copy into .{agent}/skills/)
amux agent	list / add / remove / where / agents	File-convention (copy into .{agent}/agents/)
amux hooks	discover / list / add / remove / set / handle	HookConfigManager (core)
amux doctor	--	Capability / auth / runtime diagnostics
amux tui	--	Launch interactive Ink UI (@a5c-ai/agent-mux-tui)
amux init	--	createClient() + directory creation

---

26. Version and Help

# Print version
amux --version
amux -V

# Print help
amux --help
amux -h

# Command-specific help
amux run --help
amux plugin --help
amux mcp --help

--version prints the package version of @a5c-ai/agent-mux-cli and exits with code 0.

--help prints the usage summary for the command or subcommand and exits with code 0. Help text includes a brief description, syntax, available flags, and examples.

---

27. Type Reference Summary

This section lists the key types referenced throughout the CLI spec and where they are defined.

Type	Spec	Section
AgentName, BuiltInAgentName	01-core-types-and-client.md	1.4
ErrorCode	01-core-types-and-client.md	3.1
AgentMuxError	01-core-types-and-client.md	3.1
CapabilityError	01-core-types-and-client.md	3.2
ValidationError	01-core-types-and-client.md	3.3
GlobalConfig	01-core-types-and-client.md	4.1.2
ClientOptions	01-core-types-and-client.md	5.1.1
InstalledAgentInfo	01-core-types-and-client.md	5.3.1
InstallMethod	01-core-types-and-client.md	5.3.1
RunOptions	02-run-options-and-profiles.md	2
ProfileData	02-run-options-and-profiles.md	10.2
ProfileManager	02-run-options-and-profiles.md	10
RunHandle	03-run-handle-and-interaction.md	2
RunResult	03-run-handle-and-interaction.md	3
AgentEvent	04-agent-events.md	2
AgentCapabilities	06-capabilities-and-models.md	2
ModelCapabilities	06-capabilities-and-models.md	2
SessionManager, SessionSummary, Session	07-session-manager.md	2
ConfigManager, AgentConfig	08-config-and-auth.md	2
AuthManager, AuthState	08-config-and-auth.md	8
PluginManager, InstalledPlugin, PluginListing	09-plugin-manager.md	2
McpServerConfig	02-run-options-and-profiles.md	4
RetryPolicy	01-core-types-and-client.md	5.1.1
CostRecord, CostSummary	01-core-types-and-client.md	4.2.3

---

Implementation Status (2026-04-12)

Five command surfaces have landed that extend the original spec. All are implemented under packages/cli/src/commands/.

amux install <agent> [--version V] [--force] [--dry-run] [--json]

Invokes the adapter's install(). Emits an InstallResult. Non-zero exit if ok is false. Used by the Dockerfile with HARNESSES=<csv> to pre-install harnesses into an image.

amux update <agent> [--dry-run] [--json]

Invokes the adapter's update(). Same result shape.

amux detect [<agent> | --all] [--json]

Invokes detectInstallation(). With --all iterates every registered adapter; with a specific agent returns one record. Prints installed, version, path, notes.

amux detect-host [--json]

Calls client.detectHost() and prints HostHarnessInfo { agent, confidence, source, matchedSignals } or "no harness detected". Confidence: high (≥ 2 env signals), medium (1 env signal), low (argv heuristic only).

amux remote install|update <host> [--mode ssh|docker|k8s|local] [--harness <agent>] [--force] [--json]

Four-step bootstrap over the chosen invocation mode:

1. Probe amux --version on target.
2. If missing or update/--force: npm install -g @a5c-ai/agent-mux-cli (or npm update -g).
3. amux install <harness> (or amux update <harness>) on target.
4. Verify with amux detect --all --json.

Default --mode is ssh when <host> is given, else local. Default --harness is claude-code.

Global flags actually accepted

From packages/cli/src/parse-args.ts the recognized globals are: --agent/-a, --model/-m, --json, --debug, --config-dir, --project-dir, --no-color, --version/-V, --help/-h, --completions <shell>. The top-level commands: run, install, uninstall, update, detect, detect-host, remote, adapters, capabilities, models, plugin, mcp, sessions, cost, config, profiles, auth, init, version, help.