IPC (Inter-Process Communication)

evil exposes a Unix domain socket for external tooling. You can query runtime state, list windows, take screenshots, focus windows, spawn commands, and control the session lock.

The socket path is printed at startup:

evil ipc socket at /run/user/1000/evil-ipc-*.sock

It is also available to spawned clients as the environment variable EVIL_IPC_SOCKET.

---

CLI usage

Use the evil binary with --ipc-socket and --ipc-command:

# Full runtime snapshot (JSON)
evil --ipc-socket /path/to/socket --ipc-command snapshot

# List windows (compact summary)
evil --ipc-socket /path/to/socket --ipc-command list-windows

# Focus a window by ID
evil --ipc-socket /path/to/socket --ipc-command focus-window --ipc-arg 42

# Spawn a command through the compositor
evil --ipc-socket /path/to/socket --ipc-command spawn --ipc-arg foot

# Take a screenshot
evil --ipc-socket /path/to/socket --ipc-command screenshot --ipc-arg /tmp/shot.ppm

# Session control
evil --ipc-socket /path/to/socket --ipc-command lock
evil --ipc-socket /path/to/socket --ipc-command unlock
evil --ipc-socket /path/to/socket --ipc-command quit

All responses are pretty-printed JSON. Errors exit with status 1.

---

Request types

Command	--ipc-arg required	Effect
snapshot	no	Return full RuntimeSnapshot
list-windows	no	Return compact WindowList
focus-window	yes (numeric ID)	Focus the given window
spawn	yes (shell command)	Run command through compositor
screenshot	yes (file path)	Capture screenshot to PPM
lock	no	Lock the session
unlock	no	Unlock the session
quit	no	Exit the compositor

---

Response types

Responses are tagged JSON objects.

runtime_snapshot

Full compositor state: windows, outputs, pointer, viewport, and focus stack.

{
  "type": "runtime_snapshot",
  "snapshot": {
    "focused_window_id": 1,
    "pointer": { "x": 100.0, "y": 200.0 },
    "windows": [...],
    "outputs": [...]
  }
}

window_list

Compact array of window summaries, useful for bars and launchers.

{
  "type": "window_list",
  "windows": [
    { "id": 1, "app_id": "foot", "title": "~" }
  ]
}

Fields per window summary:

• id — numeric window ID
• app_id — application ID or null
• title — window title or null

ok

Simple success confirmation.

{ "type": "ok", "message": "quit accepted" }

error

Something went wrong.

{ "type": "error", "message": "window not found" }

---

Raw JSON protocol

If you are writing a client rather than using the CLI, write a JSON object followed by a newline to the socket, then read the JSON response.

Request envelope (tagged with "type"):

{"type":"get_runtime_snapshot"}
{"type":"list_windows"}
{"type":"focus_window","id":42}
{"type":"spawn","command":"foot"}
{"type":"screenshot","path":"/tmp/shot.ppm"}
{"type":"lock"}
{"type":"unlock"}
{"type":"quit"}

The response is a single line of JSON in the same format the CLI prints.

---

Env vars

Var	Meaning
EVIL_IPC_SOCKET	Path to the active IPC socket (set for spawned clients)
EVIL_IPC_TRACE_DIR	If set, raw request/response JSONL is written here