Linux support

[tinkerbaj]

Are you planning linux support or it will be stay only for mac?

[localkin]

Hi @tinkerbaj — thanks for the interest, you're the first external issue on this repo 🙏

Short answer: yes, Linux is on the roadmap. kinclaw is macOS-only today because the 5 "claws" — screen (ScreenCaptureKit), input (CGEvent), ui (macOS Accessibility API), record (ScreenCaptureKit), plus the AppleScript-driven cerebellum skills — are all macOS-specific bindings.

What would already work on Linux today, untested

• The Go agent core: pkg/brain, pkg/skill, pkg/soul, pkg/memory
• The shell skill (POSIX shell, works anywhere)
• file_read / file_write / file_edit
• web_fetch / web_search (Go-native, uses local SearXNG)
• The new kinthink grep router + cerebellum dispatcher (Bash + awk + sed, pure POSIX)
• The web cerebellum category (curl / Playwright / Scrapling — all cross-platform)

What would need porting

• screen / input / ui / record claws — need Linux equivalents (e.g. grim+wlr-randr for Wayland, xdotool for X11, AT-SPI 2 for accessibility, OBS/ffmpeg for recording)
• AppleScript-heavy cerebellum categories (notes, mail, calendar, pages, numbers, keynote, safari, music, photos) — these would need D-Bus / freedesktop equivalents per Linux DE

The architecture is designed to allow this — each claw is a separate Go skill, not tangled into the kernel. A Linux port mostly means writing per-DE skill modules.

Direction

Embedded / IoT / robotics is exactly the natural target of the architecture — see paper #11 (Grep-Routed Agents) §3 and §8.3, which argue the cerebellum + grep-router pattern was designed to be deviceless-portable (Linux, macOS, BSD, even MCUs eventually). A working Raspberry Pi 4 port is the goal.

Priority depends on community pull. If you're willing to try a Linux PR — even just stubbing one claw (e.g. screen via grim) on one DE (e.g. GNOME or Sway) — I'd happily review and merge it. Even a linux branch in your fork with a sketchy first claw would be enough signal to move it up the priority list.

Labelled this roadmap + linux + help wanted. Will keep it open as the tracking issue.

[localkin]

Update (8 hours after my first reply) — first Linux pass landed in commit 70bbd18 on main.

What works as of today

# Build natively or cross-compile from macOS:
GOOS=linux GOARCH=amd64 go build -o kinclaw ./cmd/kinclaw      # → 17.5 MB ELF
GOOS=linux GOARCH=arm64 go build -o kinclaw ./cmd/kinclaw      # → 16.6 MB aarch64 (Raspberry Pi 4/5)

Four Linux claws shipped (pkg/skill/*_linux.go), each detecting display server at runtime and shelling out to standard Linux CLI tools:

Claw	Wayland	X11	Status
screen	grim + wlr-randr	scrot (fallback import) + xrandr + wmctrl	screenshot ✅ ; OCR / live_stream Phase 4
input	ydotool	xdotool	move / click / type / hotkey / scroll / drag / paste ✅
ui	(partial — needs AT-SPI)	xdotool + wmctrl	focused_app / window_list / window_geometry ✅ ; full a11y tree Phase 4
record	PipeWire via xdg-desktop-portal	x11grab	ffmpeg-driven start / stop / status ✅

Four Linux cerebellum categories for the new paper #11 grep router:

• linux-files — rename / copy / trash (gio) / zip / locate / tag (xattr)
• linux-apps — open (xdg-open) / launch (gtk-launch) / focus (wmctrl) / quit
• linux-settings — volume (pactl) / brightness (brightnessctl) / appearance (gsettings) / wifi (nmcli)
• linux-clipboard — set/get auto-detecting wl-clipboard / xclip / xsel

Plus a new daily-driver Linux soul: souls/pilot_linux.soul.md, with the kinthink grep router from paper #11 enabled.

What's still TODO

• Runtime testing on actual Linux. I wrote all the code from documentation in a single session and verified it cross-compiles, but have not yet booted a Pi or Ubuntu VM to smoke-test. The header comment of each *_linux.go file lists TODO(linux-verify) notes for each claw.
• AT-SPI 2 accessibility tree for ui (currently MVP via wmctrl). Phase 4. Needs godbus dep.
• Windows is blocked on github.com/LocalKinAI/kinax-go adding a Windows path (currently uses purego.RTLD_LAZY which is POSIX-only). Phase 6.

How to try it

git clone https://github.com/LocalKinAI/kinclaw
cd kinclaw
go build -o kinclaw ./cmd/kinclaw

# Install Linux tools (Wayland on Ubuntu 24.04 example):
sudo apt install grim wl-clipboard ydotool wlr-randr wmctrl xdotool xrandr scrot ffmpeg

# Run:
./kinclaw -soul souls/pilot_linux.soul.md -exec "take a screenshot"

If you try this and it breaks, please file a separate issue with the error + your DE / display server / distro. Real Linux feedback is the only way to harden the port. I'd especially appreciate testing on:

• Raspberry Pi 4 / 5 (ARM64) running Raspberry Pi OS or Ubuntu Server
• GNOME (Wayland) on Ubuntu 24.04
• Sway (Wayland) on Arch
• Xfce (X11) on any distro

New CI workflow verifies GOOS=linux GOARCH={amd64,arm64} go build on every push, so this won't regress silently.

Thanks again for the nudge — your issue moved Linux from "explicit non-goal" (roadmap as of 04-24) to "Phase 2-4 work shipped same day" (today). 🦞 → 🐧

[localkin]

Update #3 (4 hours later) — location skill now cross-platform too. Linux feature parity with the macOS pilot is at 23/24 skills (only app_open_clean remains macOS-specific; welcome-modal dismissal isn't a real Linux convention).

What's in 9fc3c3c

skills/location/SKILL.md rewritten cross-platform

Auto-detects the right backend at invocation time:

OS	Backend	Accuracy	Permission flow
macOS	corelocationcli	cell / WiFi / GPS	System Settings → Location
Linux	gdbus + Geoclue2	WiFi / Mozilla MLS	xdg-desktop-portal dialog
any	curl ipapi.co/json fallback	city-level	none (uses public IP)

Linux flow walks the standard Geoclue2 D-Bus interaction (Manager.GetClient → Set DesktopId + accuracy → Client.Start → poll Location property → read Lat/Lon/Description → Client.Stop). For format=address / format=city it then hits OpenStreetMap Nominatim for reverse geocoding (no API key, no rate-limit headache for personal use).

If Geoclue2 doesn't return a fix within 10s (common on Sway/i3 where portal dialogs don't auto-render, or on servers without WiFi positioning), it auto-falls-back to ipapi.co — still useful, just city-level.

location                        → "37.7749,-122.4194"
location format=address         → "5 Cyclamen Way, Cupertino, CA, USA"
location format=city            → "Cupertino"
location format=full            → multi-line: lat/lon/altitude/accuracy/description

Linux setup recap (now with location)

# Ubuntu / Debian
sudo apt install grim wl-clipboard ydotool wlr-randr wmctrl \
                 xdotool xrandr scrot ffmpeg brightnessctl \
                 geoclue-2.0 jq curl

# Fedora
sudo dnf install grim wl-clipboard ydotool wlr-randr wmctrl \
                 xdotool xorg-x11-server-Xorg scrot ffmpeg \
                 brightnessctl geoclue2 jq curl

# Arch
sudo pacman -S grim wl-clipboard ydotool wlr-randr wmctrl \
              xdotool xorg-xrandr scrot ffmpeg brightnessctl \
              geoclue jq curl

# Verify
systemctl status geoclue.service  # should be active

Testing ask 🦞 → 🐧

@tinkerbaj — would you be willing to clone main and smoke-test on your actual Linux box?

git clone https://github.com/LocalKinAI/kinclaw
cd kinclaw
go build -o kinclaw ./cmd/kinclaw

# Minimal smoke test (doesn't need any external installs):
./kinclaw -soul souls/pilot_linux.soul.md -exec "echo hello from linux"
./kinclaw -soul souls/pilot_linux.soul.md -exec "what is the current date"

# Then progressively (each tests one claw):
./kinclaw -soul souls/pilot_linux.soul.md -exec "take a screenshot"
./kinclaw -soul souls/pilot_linux.soul.md -exec "what's my GPS location"
./kinclaw -soul souls/pilot_linux.soul.md -exec "list my running windows"
./kinclaw -soul souls/pilot_linux.soul.md -exec "set the system volume to 50 percent"

What I'd love to learn from you:

1. Which distro + DE you're running (so I can tag bugs accurately)
2. Which of the 4 claws break when invoked — error messages > screenshots
3. Geoclue2 behavior — does it return a fix? Does the portal dialog appear? Or does it fall back to IP?
4. Anything that fails silently — the most painful bugs are the ones where it just hangs or returns nothing

File new issues with the label linux and include:

• distro + version (e.g. Ubuntu 24.04 / GNOME / Wayland)
• claw / cerebellum action that broke
• the exact kinclaw -exec "..." you ran
• the error output

If you can't test but know someone who can, please pass the link — community testing is the only way this gets out of "TODO(linux-verify)" status. All the Linux code was written from documentation in a single session; I have not yet booted Linux to run it. The cross-compile succeeds and Go-level interfaces match, but actual grim/ydotool/gdbus behavior on real hardware is unverified.

Thank you for opening this issue. Without you nudging the conversation, kinclaw would still be macOS-only. 🙏

[localkin]

Update #4 — ui claw now full AT-SPI 2 on Linux (commit 65b07a0)

Closes the last big macOS/Linux capability gap from yesterday. pkg/skill/ui_linux.go upgraded from xdotool-only MVP to accessibility-tree walking via godbus, mirroring the macOS uiSkill's AX tree depth.

New ui actions on Linux

Action	Backend	Notes
focused_app	xdotool	unchanged
window_list	wmctrl	unchanged
window_geometry	xdotool	unchanged
tree [depth=4] [app=…]	AT-SPI 2 via D-Bus	indented dump of the a11y tree
find name=X role=Y	AT-SPI 2 via D-Bus	breadcrumb-path search
click_by_name name=X	AT-SPI 2 via D-Bus	invokes Action.DoAction(0)
click_by_role role=Y	AT-SPI 2 via D-Bus	same

D-Bus dance

session bus → org.a11y.Bus.GetAddress  →  dedicated a11y bus
                                          │
                                          ▼
                          /org/a11y/atspi/accessible/root
                          on org.a11y.atspi.Registry
                                          │
                          (Accessible: Name / GetRoleName / GetChildAtIndex)
                                          │
                          (Action:     GetNActions / DoAction)

Dependency added

github.com/godbus/dbus/v5 v5.2.2 — pure Go, no cgo, MIT. Binary
size impact: +0.5 MB on Linux amd64 (17.5 → 18.0 MB). macOS binary
unaffected (_other.go stub).

Testing ask (renewed)

@tinkerbaj — when you find time, the most useful tests for this round are:

# Prerequisites for AT-SPI:
sudo apt install at-spi2-core         # Ubuntu / Debian
# or
sudo dnf install at-spi2-core         # Fedora
# or
sudo pacman -S at-spi2-core           # Arch

# GNOME usually has it on by default; verify:
systemctl --user status at-spi-dbus-bus.service

# Then:
./kinclaw -soul souls/pilot_linux.soul.md -exec "use the ui skill to show me the accessibility tree, max depth 3"
./kinclaw -soul souls/pilot_linux.soul.md -exec "find a button containing 'Save' in the focused app"
./kinclaw -soul souls/pilot_linux.soul.md -exec "click the OK button in any dialog"

What I most need to verify:

1. AT-SPI bus discovery — does org.a11y.Bus.GetAddress return a valid address on your distro? (If at-spi2-core isn't running, tree will error cleanly with a message — that's also useful signal.)
2. Property type matches — I assumed ChildCount returns int32 and Name returns string. Some old at-spi2-core versions used different types.
3. DoAction(0) — does it actually click? GNOME apps usually expose "click" as action index 0 on Button accessibles, but some custom widgets number differently.
4. Wayland behavior — GNOME-Wayland should have an a11y bridge, but I've never tested. Sway / Hyprland likely return an empty registry (graceful: tree says "(no top-level apps found)").

If any of these fails, the error message + your distro/DE/version is all I need to fix it. Phase 6 (Windows) is now the only remaining blocker, gated on kinax-go adding a Windows path — separate upstream PR.

🦞🐧 — Linux feature parity with macOS pilot:

• macOS pilot: 24 skills
• Linux pilot: 23 skills (only app_open_clean remains macOS-only; that's a welcome-modal convention, not really a Linux thing)

[localkin]

Phase 6 (Windows) shipped overnight — same 2026-05-12 day as Linux (d7cee60)

@tinkerbaj — the kinax-go Windows blocker I mentioned earlier turned out to be sidestep-able by build-tag-splitting the macOS-only callers (pkg/probe, pkg/applifecycle, the serve preflight + livefeed in cmd/kinclaw) rather than waiting on an upstream Windows path in kinax-go. So Windows now ships in the same release as Linux.

Windows surface (same skill API as macOS + Linux)

Claw	Backend	Source
screen	PowerShell + System.Drawing.Graphics.CopyFromScreen (full / region / list_displays)	pkg/skill/screen_windows.go
input	user32.dll P/Invoke (SetCursorPos, mouse_event) + System.Windows.Forms.SendKeys for text/hotkeys	pkg/skill/input_windows.go
ui	UI Automation 2.0 (UIAutomationClient + UIAutomationTypes) — same actions as Linux AT-SPI 2 path: tree, find, click_by_name, click_by_role, plus focused_app / window_list / window_geometry via user32	pkg/skill/ui_windows.go
record	ffmpeg -f gdigrab -i desktop (libx264 ultrafast, yuv420p)	pkg/skill/record_windows.go

Plus 4 cerebellum categories (windows-files, windows-apps, windows-settings, windows-clipboard) and a Windows pilot soul (souls/pilot_windows.soul.md) at 23 skills.

Builds

GOOS=windows GOARCH=amd64 → 17 MB kinclaw.exe ✅
GOOS=windows GOARCH=arm64 → 16 MB kinclaw.exe ✅ (Surface, Snapdragon X)

CI matrix now requires both. PowerShell 5.1 (ships in-box from Win 7 SP1 onward) is the only runtime dep besides ffmpeg for record.

Status

Same as Linux: code complete, awaiting community runtime testing. I don't have a Windows box to validate against, so the things most likely to need refinement once someone runs it:

1. PowerShell heredoc escaping (one backtick clash caught during build; more may surface)
2. UIA InvokePattern availability on UWP apps (Win32 buttons fine; UWP sometimes only exposes SelectionItemPattern)
3. Windows.Devices.Radios toggle for Wi-Fi/Bluetooth (may need admin on some configs)
4. ffmpeg gdigrab on Windows 11 with DRM-protected windows (will show black areas)
5. key_down/key_up is degraded — SendKeys auto-releases. True modifier-hold needs raw SendInput + KEYEVENTF_KEYDOWN/KEYUP (future work).

If you can grab a Windows binary off the next CI run (artifacts up for 7 days) and try a few common flows — screen screenshot, ui focused_app, input click, cerebellum 'windows-clipboard set hello' — reports back here would be hugely appreciated. Both ✅ and ❌ are useful.

CHANGELOG entry: 2026-05-12 (overnight). Roadmap update: Phase 6 section.