How do I install the Niri Ipc skill?

Run npx skillmds@latest add modbender/niri-ipc in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Niri Ipc safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Niri Ipc?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Niri Ipc free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Niri Ipc?

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Niri Ipc by modbender — Agent Skill

Name: Niri Ipc
Rating: 4.2 (5 reviews)
Author: modbender

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.

modbender Updated Sep 9, 2026 12 repo stars

File contents

Niri IPC

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.

---name: niri-ipcdescription: 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.--- # Niri IPC 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`): ```bash ./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: ```bash # 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): ```bash # 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: ```bash # 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: ```bash ./skills/niri-ipc/scripts/niri.py output --help ``` ## Working directly with `niri msg` If you don’t want the helper script, call Niri directly: ```bash 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. ```bash # 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.

Frequently asked questions