IPC Socket

Overview

Reference

IPC Socket

SamWM exposes a Unix socket for runtime control. Clients can send commands and receive responses for scripting, status bars, and automation.

Socket Path

The socket is created at:

$XDG_RUNTIME_DIR/samwm.sock

For example:

/run/user/1000/samwm.sock

Protocol

The protocol is simple text-based, newline-delimited:

Client connects to the socket
Client sends a command (one per line, terminated by \n)
Server sends a response (one per line)
Server closes connection after response (or keeps it open for subscription commands)

Response Format

OK <data>
ERR <message>

Commands

General

Command	Description	Example
`version`	Get SamWM version	`OK 0.1.0`
`workspaces`	List all workspaces	`OK [{"id":1,"windows":2},...]`
`active-workspace`	Get current workspace	`OK 1`

Windows

Command	Description	Example
`windows`	List all windows	`OK [{"id":1,"title":"Firefox",...},...]`
`focused`	Get focused window	`OK {"id":1,"title":"..."}`
`window <id>`	Get window info	`OK {"id":1,...}`

Workspace Control

Command	Description	Example
`workspace <n>`	Switch to workspace	`OK`
`movetoworkspace <n>`	Move focused window	`OK`

Layout

Command	Description	Example
`layouts`	List available layouts	`OK ["master-stack","dwindle","bsp","columns","floating","fullscreen"]`
`setlayout <name>`	Set current layout	`OK`

Config

Command	Description	Example
`reload`	Hot-reload config	`OK`
`get <key>`	Get config value	`OK {"key":"value"}`

Subscriptions (event stream)

Command	Description
`subscribe window`	Stream window events
`subscribe workspace`	Stream workspace events
`subscribe active`	Stream focus changes

Events are sent as JSON:

{"type":"window_open","data":{"id":1,"title":"Firefox"}}
{"type":"window_close","data":{"id":1}}
{"type":"workspace_change","data":{"from":1,"to":2}}
{"type":"focus_change","data":{"window_id":3}}

Client Examples

Shell (netcat)

echo "version" | nc -uU /run/user/1000/samwm.sock

Shell (socat)

echo "workspaces" | socat - UNIX-CONNECT:/run/user/1000/samwm.sock

Go

package main

import (
    "net"
    "fmt"
)

func main() {
    conn, err := net.Dial("unix", "/run/user/1000/samwm.sock")
    if err != nil {
        panic(err)
    }
    defer conn.Close()

    fmt.Fprintln(conn, "version")
    buf := make([]byte, 1024)
    n, _ := conn.Read(buf)
    fmt.Println(string(buf[:n]))
}

Python

import socket

sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect("/run/user/1000/samwm.sock")
sock.sendall(b"workspaces\n")
response = sock.recv(4096)
print(response.decode())
sock.close()

Waybar Module

In your ~/.config/waybar/config:

"custom/samwm-workspaces": {
    "exec": "samwm-msg workspaces",
    "interval": 1,
    "return-type": "json",
    "format": "{}",
    "on-click": "samwm-msg workspace {}"
}

CLI Tool

SamWM includes a companion CLI tool (samwm-msg) for common operations:

# Get version
samwm-msg version

# Switch workspace
samwm-msg workspace 2

# List windows
samwm-msg windows

# Hot reload config
samwm-msg reload

# Set layout
samwm-msg setlayout dwindle

Install alongside SamWM, or use the IPC socket directly from any language.

Animations