StepForge/docs/GETTING_STARTED_WITH_LINUX.md

Getting Started with StepForge on Linux

⚠️ Work in progress. Linux support is still under active development. Expect rough edges — especially on Wayland (see the limitations below). X11 / Xorg is the most complete path today. Please report issues.

StepForge was built on Windows, where the OS lets an app watch every click and grab the screen freely. Linux is more restrictive, and how much works depends on whether you are running X11 (Xorg) or Wayland. This guide explains the difference, how to get the best experience, and how to enable per-click capture.

TL;DR

	X11 / "Ubuntu on Xorg"	Wayland (default on Ubuntu)
Screenshot per click	✅ Yes	✅ Yes (needs input group)
Red circle on the click	✅ Yes	❌ No (Wayland hides the cursor position)
"Share your screen" prompt	Never	Once per recording session
Setup needed	None	Add yourself to the input group

If you want the full Windows-like experience (click capture with the red marker), use an Xorg session — see Option A.

---

1. Check which session you are running

echo $XDG_SESSION_TYPE

• x11 → you're on Xorg. Everything works, including the red click marker. No setup needed.
• wayland → you're on Wayland. Read on.

---

Option A (best experience) — use Xorg

On Xorg, StepForge captures a screenshot on every click and draws the red marker at the exact click position, exactly like Windows. No dependencies, no permissions, no portal dialogs.

To switch:

1. Log out.
2. On the login (password) screen, click the ⚙ gear icon in the bottom-right corner.
3. Choose "Ubuntu on Xorg".
4. Log back in.

That's it — open StepForge and record. (To go back to Wayland later, pick "Ubuntu" at the gear menu again.)

---

Option B — stay on Wayland

Wayland deliberately blocks apps from monitoring global input and from grabbing the screen silently. StepForge works around this as far as the platform allows:

Screen capture

The first time you press Start recording, the system shows a "Share your screen" dialog (the XDG desktop portal). Pick your screen and click Share. This happens once per recording session — not per screenshot. The shared stream stays open until you stop recording.

If you never see steps appear, make sure you actually picked a screen and clicked Share in that dialog.

Per-click capture (requires the input group)

By default on Wayland, StepForge cannot see your clicks, so it falls back to capturing a screenshot every few seconds (timed capture).

To get a screenshot on every click instead, give your user read access to the mouse devices by joining the input group:

sudo usermod -aG input "$USER"

Then log out and log back in (group membership only applies to new sessions). Verify it took effect:

groups | tr ' ' '\n' | grep input    # should print: input

Now StepForge reads mouse buttons directly from the kernel (/dev/input) and captures a screenshot on each click.

No red marker on Wayland. Even with per-click capture working, Wayland does not tell apps where the pointer is, so StepForge cannot draw the circle at the click. The screenshot is still captured per click — just without the marker. If you need the marker, use Option A (Xorg).

Adjusting the timed-capture interval

If you don't enable the input group, StepForge captures on a timer. Change the fallback in Settings → Capture:

• When clicks are unavailable -> Hotkey only to use the Capture hotkey instead of a timer.
• When clicks are unavailable -> Timed interval, then set Timer interval (seconds) (capture.autoIntervalSec, default 5 seconds) if you want timed captures.

---

How StepForge picks a capture method (for reference)

On launch StepForge chooses the best available click source:

1. Windows — low-level mouse hook (position + timing).
2. X11 — xinput (position + timing → full red marker).
3. Linux evdev (/dev/input) — button presses on X11 and Wayland, no position on Wayland. Used when xinput can't see clicks (i.e. Wayland), if you're in the input group.
4. Timed capture — the always-works fallback (a screenshot every N seconds) when no click source is available.

Screen frames come from a single long-lived capture stream per recording, so clicks/timer ticks never re-open the screen-share dialog.

---

Troubleshooting

"It asks to share my screen every time." You're likely on an older build. Update to the current version — the screen stream is now opened once per recording session. If it persists, confirm echo $XDG_SESSION_TYPE and that you clicked Share (not Cancel) in the dialog.

"Recording captures a couple of steps then stops." Fixed in the current version (a slow, GPU-less PNG encode used to trip a failure guard and tear down the stream). Update and retry.

"The window disappeared and I can't stop the recording." On Linux the window minimizes while recording (GNOME's system tray is unreliable). Bring it back from the taskbar / dock, then click Stop recording.

"No steps at all on Wayland, even after picking a screen." Run from a terminal with logging and look for the diagnostic lines:

STEPFORGE_CAPTURE_LOG=1 npm start

• [stepforge] screen-capture stream active … — the stream is up.
• [stepforge] per-click capture via evdev on N device(s) … — clicks are wired up.
• [stepforge] no readable mouse input devices … — you need the input group (see above).

Harmless console noise. Lines like vaInitialize failed, Frame latency is negative, and StatusNotifierItem … already exported come from Chromium/GNOME, not StepForge, and don't affect recording.