Niri IPC

Control the Niri Wayland compositor on Linux via its IPC (`niri msg --json` / $NIRI_SOCKET). Use when you need to query Niri state (outputs/workspaces/windows/focused window) or perform actions (focus/move/close windows, switch workspaces, spawn commands, reload config) from an OpenClaw agent running on a Niri session.

Security Scan

The skill is generally consistent with controlling the Niri compositor, but it omits declaring required environment/binary dependencies and its runtime instructions allow executing arbitrary commands (including shell-spawn) while model invocation is permitted — this combination deserves caution.

Purpose & Capability

The name, description, SKILL.md and bundled scripts (scripts/niri.py, scripts/niri_ctl.py, scripts/niri_socket.py) all align with a Niri IPC helper: they wrap `niri msg` and $NIRI_SOCKET operations and provide window/workspace actions. However, the skill declares no required env vars or binaries even though the instructions explicitly assume $NIRI_SOCKET and the `niri msg` CLI are available. The omission of these declared requirements is an inconsistency (should at least list NIRI_SOCKET and niri).

Instruction Scope

The SKILL.md stays on-topic (querying state, focusing/moving/closing windows, spawning programs, streaming events). It documents using helper scripts and direct socket access. A notable point: the documented actions include 'spawn' and 'spawn-sh' — the latter runs commands through the shell, so the skill provides a mechanism to execute arbitrary shell commands on the host. That behavior is coherent with compositor control but is sensitive and worth flagging.

Install Mechanism

There is no install spec (instruction-only skill with bundled scripts). No external downloads or package installs are requested, so nothing is written to disk by an installer beyond the included files. This is lower installation risk.

Credentials

The skill requires access to the Niri socket and the `niri msg` CLI in practice, but requires.env and primary credential fields are empty. The SKILL.md references $NIRI_SOCKET and running inside a Niri session; these should have been declared. Also, since the skill can spawn arbitrary commands (including via shell), any environment or file the spawned commands access becomes relevant — the skill requests broader runtime privileges than are declared.

Persistence & Privilege

The skill is not set always:true (good), but disable-model-invocation is not set, so the model can invoke this skill autonomously. Combined with documented spawn and spawn-sh actions that can run arbitrary processes/commands, this creates a risk surface: an autonomously-invoked skill could execute commands on the host. For a compositor control tool this ability may be reasonable, but it is sensitive and should be intentionally restricted or documented.

What to consider before installing

This skill appears to genuinely be for controlling a Niri session, but take these precautions before installing: 1) Only install if you run the Niri compositor and trust the skill owner; the skill assumes $NIRI_SOCKET and the `niri msg` CLI but does not declare them — confirm those prerequisites. 2) Review the bundled scripts (scripts/niri.py, niri_ctl.py, niri_socket.py) yourself to verify what they execute; pay attention to the implementation of spawn/spawn-sh to see how they invoke the shell. 3) If you do not want the agent to execute arbitrary commands automatically, set disable-model-invocation:true or require explicit user invocation for this skill. 4) Prefer running the skill in a limited environment or session (not a privileged/root session) and avoid installing it into agents that have broad access to sensitive data or credentials.

Use Niri IPC through the niri msg CLI (preferred) or by writing JSON requests to $NIRI_SOCKET.

This skill assumes:

• You are on Linux with Niri running.
• $NIRI_SOCKET is set (usually true inside the Niri session).

Quick start (recommended)

Use the bundled helper script (wrapper around niri msg --json):

./skills/niri-ipc/scripts/niri.py version
./skills/niri-ipc/scripts/niri.py outputs
./skills/niri-ipc/scripts/niri.py workspaces
./skills/niri-ipc/scripts/niri.py windows
./skills/niri-ipc/scripts/niri.py focused-window

Deeper control

1) High-level helpers (window matching)

Use scripts/niri_ctl.py when you want to refer to windows by title/app_id substring instead of ids:

# List windows (optionally filtered)
./skills/niri-ipc/scripts/niri_ctl.py list-windows --query firefox

# Focus a window by substring match
./skills/niri-ipc/scripts/niri_ctl.py focus firefox

# Close a matched window (focus then close)
./skills/niri-ipc/scripts/niri_ctl.py close firefox

# Move a matched window to a workspace (by index or by name)
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox 3
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox web

# Focus a workspace by index or name
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace 2
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace web

2) Full IPC access (raw socket)

Use scripts/niri_socket.py to talk to $NIRI_SOCKET directly (newline-delimited JSON):

# Send a simple request (JSON string)
./skills/niri-ipc/scripts/niri_socket.py raw '"FocusedWindow"'

# Batch requests: one JSON request per line on stdin
printf '%s\n' '"FocusedWindow"' '"Workspaces"' | ./skills/niri-ipc/scripts/niri_socket.py stdin

# Event stream (prints JSON events until interrupted)
./skills/niri-ipc/scripts/niri_socket.py event-stream

Actions

Pass through Niri actions:

# Focus workspace by index
./skills/niri-ipc/scripts/niri.py action focus-workspace 2

# Move focused window to workspace
./skills/niri-ipc/scripts/niri.py action move-window-to-workspace 3

# Focus a window by id
./skills/niri-ipc/scripts/niri.py action focus-window 123

# Close focused window
./skills/niri-ipc/scripts/niri.py action close-window

# Reload niri config
./skills/niri-ipc/scripts/niri.py action load-config-file

# Spawn (no shell)
./skills/niri-ipc/scripts/niri.py action spawn -- alacritty

# Spawn through shell
./skills/niri-ipc/scripts/niri.py action spawn-sh -- 'notify-send hello'

Output configuration

Use niri msg output ... via the wrapper:

./skills/niri-ipc/scripts/niri.py output --help

Working directly with niri msg

If you don’t want the helper script, call Niri directly:

niri msg --json windows
niri msg --json action focus-workspace 2

Tip: if niri msg parsing errors happen after upgrades, restart the compositor (new niri msg against old compositor is a common mismatch).

Event stream

For status bars/daemons: Niri can stream events.

# Raw JSON event lines (runs until interrupted)
./skills/niri-ipc/scripts/niri.py event-stream

# Just a few lines for a quick test
./skills/niri-ipc/scripts/niri.py event-stream --lines 5

Troubleshooting

• If commands fail with “NIRI_SOCKET is not set”: run inside your Niri session, or export the socket path.
• If you need the socket protocol details, read: ./skills/niri-ipc/references/ipc.md.
• If your goal is complex automation (pick the right window by title/app_id, etc.), first query windows, then act by window id.