IPC Socket

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,"name":"1","active":true,"layout":"master-stack"},...]`
`active-workspace`	Get current workspace	`OK {"id":1,"name":"1","layout":"master-stack"}`

Windows

Command	Description	Example
`windows`	List windows on active workspace	`OK [{"address":1234,"title":"Firefox","class":"firefox","workspace":1,"floating":false,"fullscreen":false,"focused":true},...]`
`focused`	Get focused window	`OK {"address":1234,"title":"Firefox","class":"firefox","workspace":1}`
`window <id>`	Get window info by numeric address	`OK {"address":1234,"title":"Firefox",...}`

Workspace Control

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

Layout

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

Config

Command	Description	Example
`reload`	Hot-reload config from file	`OK`
`get <key>`	Get config value (border_size, gaps_inner, gaps_outer, focus_follows_mouse)	`OK 5`

Subscriptions (persistent connection)

Command	Description
`subscribe window`	Stream window_open / window_close events
`subscribe workspace`	Stream workspace_change events
`subscribe focus`	Stream focus_change events

When you send a subscribe command, the connection stays open and streams events as they occur. Disconnect to stop receiving.

Events are sent as JSON:

{"type":"window_open","data":{"id":123456789,"title":"Firefox","class":"firefox"}}
{"type":"window_close","data":{"id":123456789}}
{"type":"workspace_change","data":{"from":1,"to":2}}
{"type":"focus_change","data":{"window_id":123456789}}
{"type":"reload","data":{"status":"reloaded"}}

Client Examples

Shell (netcat / socat)

# One-shot commands
echo "version" | socat - UNIX-CONNECT:/run/user/1000/samwm.sock
echo "workspaces" | socat - UNIX-CONNECT:/run/user/1000/samwm.sock

# Subscribe to events (connection stays open)
echo "subscribe window" | socat - UNIX-CONNECT:/run/user/1000/samwm.sock
# Events stream in until you disconnect

Go

package main

import (
    "fmt"
    "net"
    "os"
)

func main() {
    sock := os.Getenv("XDG_RUNTIME_DIR") + "/samwm.sock"
    conn, err := net.Dial("unix", sock)
    if err != nil {
        panic(err)
    }
    defer conn.Close()

    // One-shot command
    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

# List all workspaces
samwm-msg workspaces

# Get current workspace
samwm-msg active-workspace

# Switch workspace
samwm-msg workspace 2

# Move focused window to workspace
samwm-msg movetoworkspace 3

# List windows on active workspace
samwm-msg windows

# Get focused window
samwm-msg focused

# Get window by ID
samwm-msg window 123456789

# List available layouts
samwm-msg layouts

# Set workspace layout
samwm-msg setlayout dwindle

# Hot reload configuration
samwm-msg reload

# Get config value
samwm-msg get border_size
samwm-msg get gaps_inner
samwm-msg get gaps_outer
samwm-msg get focus_follows_mouse

The samwm-msg binary is built alongside SamWM and can be placed anywhere in your PATH.

Animations