feat: add claude-companion

[lowcache]

Plugin

• Id: lowcache/claude-companion
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

Claude Code's live status on your desktop: a breathing pulse widget on the bar and an ambient orb desktop widget that reflect what your agent is doing (working, needs you, idle), an answer panel for /claude ? quick questions, and launch a /claude session from within Noctalia's Launcher. An MCP shim gives Claude live desktop senses and hands (windows, media, power, network; theme/workspace/wallpaper control) across niri, Hyprland, and Sway. The terminal still does the real agentic work — this gives claude a hands that reach right into your shell.

External dependencies

claude, python3, niri/hyprctl/swaymsg, playerctl, nmcli, notify-send

Testing

• Tested on Niri
• Tested on Hyprland
• Tested on Sway
• Tested on another compositor:
• Noctalia version tested against: 5.0.0
• Plugin API level: 3

Screenshots / Videos

Checklist

• The directory name matches the part of id after the / in plugin.toml exactly.
• It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
• README.md follows the
  README template, documents
  every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
• I created thumbnail.webp with the thumbnail generator.
• version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
• Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and
  understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
• I did not edit catalog.toml; CI generates it.
• This PR touches exactly one plugin directory.

Code review attestation

Plugins run as trusted, unsandboxed Luau in the user's session. Confirm:

• The code is readable and not obfuscated, minified, or generated.
• It does not download and execute remote code.
• Every network call, filesystem write, and spawned process is something the description above accounts for.
• I have the right to publish this code under the license declared in plugin.toml.

[ItsLemmy]

• 1. blocking - claude-companion/shim/noctalia-mcp.py:103

The Sway mutators interpolate caller-controlled window and workspace references directly into swaymsg's command language. claude-companion/shim/noctalia-mcp.py:104 and claude-companion/shim/noctalia-mcp.py:105 have the same issue. swaymsg supports command separators and immediately executes the resulting
Sway command, so a value containing an additional exec command can turn a narrowly approved MCP desktop action into arbitrary command execution.
Validate identifiers and workspace references against strict safe syntax before constructing Sway commands.

2. blocking - claude-companion/claude.luau:49

The /claude ? path is described as read-only at claude-companion/README.md:81, but the generated claude -p command does not disable built-in tools, inherited MCP servers, plugins, hooks, or user/project settings. On a system with pre-authorized tools, a quick question can therefore run commands or
modify files despite the read-only promise. Launch this path with an isolated, tool-free configuration or stop presenting it as read-only and expose the actual permission behavior.

3. blocking - claude-companion/shim/noctalia-mcp.py:288

The advertised get_processes tool shells out to ps at claude-companion/shim/noctalia-mcp.py:290, but ps is absent from the manifest dependencies at claude-companion/plugin.toml:18 and the requirements at claude-companion/README.md:45. Repository policy requires spawned external commands to be declared and documented.

4. non-blocking - claude-companion/README.md:23

The README says an offline widget spec suite keeps the state machine tested, and claude-companion/shim/noctalia-mcp.py:50 points to tests/shim_spec.py, but the PR contains no test directory or plugin-specific tests. Remove these claims or include the referenced tests.

[lowcache]

I included tests/ and fixed the other issues you found. I also used the opportunity to run another pass of my own and a couple things came up. So I appreciate the impetus that helped make the plugin better. A state.watch subscription the bar pulse relied on never actually fired, so quick-ask progress didn't show. I switched it to polling and fixed a lazy test in my dev repo that took a shortcut. I am switching to my terminal to commit and push the changes now.

[ItsLemmy]

Almost there.

• Add tr and timeout as dependencies in the README.
• The thumbnail does not look great with the super long description, I would keep it short, this is not a readme.

[ItsLemmy]

Thanks