maomaowm/docs/ipc.md

title	description
IPC	Control mangowm programmatically using mmsg.

mmsg(1) - User Manual

mmsg is the command-line interface for the Mango compositor's Inter-Process Communication (IPC) system. It allows users and scripts to query the state of the compositor or subscribe to real-time events.

SYNOPSIS

mmsg <command> [arguments...]

DESCRIPTION

mmsg acts as a client that connects to the Mango compositor via a Unix domain socket defined by the MANGO_INSTANCE_SIGNATURE environment variable. It supports two primary modes of operation:

1. One-shot Request (get): Sends a query to the compositor, receives a single JSON response, and terminates.
2. Persistent Stream (watch): Subscribes to a specific state, receiving continuous JSON updates whenever that state changes.

ENVIRONMENT VARIABLES

• MANGO_INSTANCE_SIGNATURE: Must be set to the path of the Unix socket created by the running Mango instance. This is typically handled automatically when running mmsg from within a terminal spawned by the compositor.

COMMANDS

GET (One-Shot Queries)

Command	Description
get version	Returns the current version of the compositor.
get keymode	Returns the current active keyboard mode (e.g., normal, insert).
get keyboardlayout	Returns the active XKB layout (abbreviated).
get monitor <name>	Returns full JSON details for a specific monitor.
get client <id>	Returns full JSON details for a client with the given ID.
get tag <mon> <idx>	Queries status of a specific tag on a monitor.
get all-clients	Returns a JSON array of all active clients.
get all-monitors	Returns a JSON array of all connected monitors.
get all-tags	Returns a JSON object containing the status of all tags.
get last_open_surface <mon>	Returns the last focused surface name for a monitor.

Example:

mmsg get monitor eDP-1
mmsg get all-clients
mmsg get all-monitors

WATCH (Event Subscription)

Subscribes the client to real-time updates. When the state changes, the server pushes a new JSON object to the output stream.

• watch monitor <name>
• watch client <id>
• watch tags <mon_name>
• watch all-monitors
• watch all-tags
• watch all-clients
• watch keymode
• watch keyboardlayout
• watch last_open_surface <mon_name>

Example:

# watch all monitors
mmsg watch all-monitors
# watch all tags
mmsg watch all-tags

DISPATCH

Allows sending commands to the compositor to alter its state.

• dispatch <func_name>,[args...] [client,<id>]

Example:

# operate specific client by id
mmsg dispatch exchange_client,left client,375
# operate current client
mmsg dispatch exchange_client,left