Socket API Reference

wmux exposes a JSON-RPC API over a Windows named pipe for programmatic control. Compatible with the cmux v2 protocol.

Connection

Connect to the named pipe at \\.\pipe\wmux. Messages are newline-delimited JSON.

Protocol

Request Format

{"id": "string", "method": "string", "params": {}}

Success Response

{"id": "string", "ok": true, "result": {}}

Error Response

{"id": "string", "ok": false, "error": {"code": "string", "message": "string"}}

System Methods

system.ping

Health check. Returns a pong response.

Params

None

Response

{"pong": true}

Example

// Request
{"id": "1", "method": "system.ping", "params": {}}

// Response
{"id": "1", "ok": true, "result": {"pong": true}}

system.capabilities

Returns the server version and list of available commands.

Params

None

Response

{"version": "0.1.0", "commands": ["system.ping", "workspace.list", ...]}

Workspace Methods

workspace.list

List all workspaces.

Params

None

Response

{"workspaces": [{"id": "uuid", "name": "string", "index": 0}]}

Example

// Request
{"id": "2", "method": "workspace.list", "params": {}}

// Response
{"id": "2", "ok": true, "result": {"workspaces": [
  {"id": "a1b2c3d4", "name": "Project Alpha", "index": 0},
  {"id": "e5f6g7h8", "name": "Dev Server", "index": 1}
]}}

workspace.create

Create a new workspace.

Params

Name	Type	Required	Description
`name`	string	No	Display name for the workspace

Response

{"id": "uuid"}

Example

// Request
{"id": "3", "method": "workspace.create", "params": {"name": "Testing"}}

// Response
{"id": "3", "ok": true, "result": {"id": "f9a8b7c6"}}

workspace.select

Switch to a workspace by ID.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Workspace ID to select

Response

{}

workspace.current

Get the currently active workspace.

Params

None

Response

{"id": "uuid", "name": "string", "index": 0}

workspace.close

Close a workspace and all its surfaces.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Workspace ID to close

Response

{}

Surface Methods

surface.list

List all surfaces, optionally filtered by workspace.

Params

Name	Type	Required	Description
`workspace_id`	uuid	No	Filter to a specific workspace

Response

{"surfaces": [{"id": "uuid", "focused": true}]}

surface.split

Split the currently focused surface.

Params

Name	Type	Required	Description
`direction`	string	Yes	`"vertical"` or `"horizontal"`

Response

{"id": "uuid"}

Example

// Request
{"id": "10", "method": "surface.split", "params": {"direction": "vertical"}}

// Response
{"id": "10", "ok": true, "result": {"id": "d4e5f6a7"}}

surface.focus

Focus a specific surface.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Surface ID to focus

Response

{}

surface.close

Close a surface.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Surface ID to close

Response

{}

surface.send_text

Send text input to a surface's terminal.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Target surface ID
`text`	string	Yes	Text to send

Response

{}

Example

// Request
{"id": "20", "method": "surface.send_text", "params": {
  "id": "d4e5f6a7",
  "text": "cargo test\n"
}}

// Response
{"id": "20", "ok": true, "result": {}}

surface.send_key

Send a special key or key combination to a surface.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Target surface ID
`key`	string	Yes	Key name to send

Supported Keys

Enter, Tab, Escape, Backspace, Up, Down, Left, Right, Home, End, Delete, F1-F12, Ctrl+C, Ctrl+D, Ctrl+Z, Ctrl+L, Ctrl+A

Response

{}

surface.read_output

Read the terminal output from a surface.

Params

Name	Type	Required	Description
`id`	uuid	Yes	Target surface ID
`rows`	number	No	Number of rows to read (from bottom)

Response

{"output": "string"}

Example

// Request
{"id": "30", "method": "surface.read_output", "params": {
  "id": "d4e5f6a7",
  "rows": 10
}}

// Response
{"id": "30", "ok": true, "result": {
  "output": "running 62 tests\ntest result: ok. 62 passed\n"
}}

PowerShell Connection Example

Here is a complete example of connecting to the wmux socket from PowerShell:

# Connect to the wmux named pipe
$pipe = New-Object System.IO.Pipes.NamedPipeClientStream(
  ".", "wmux", [System.IO.Pipes.PipeDirection]::InOut
)
$pipe.Connect(5000)

$writer = New-Object System.IO.StreamWriter($pipe)
$reader = New-Object System.IO.StreamReader($pipe)
$writer.AutoFlush = $true

# Send a ping
$writer.WriteLine('{"id":"1","method":"system.ping","params":{}}')
$response = $reader.ReadLine()
Write-Host $response
# {"id":"1","ok":true,"result":{"pong":true}}

# List workspaces
$writer.WriteLine('{"id":"2","method":"workspace.list","params":{}}')
$response = $reader.ReadLine()
Write-Host $response

# Clean up
$pipe.Close()