Skip to content

Usage

Jump to bottom
Joshua Hirsig edited this page Jun 30, 2026 · 3 revisions

Usage

stepshot runs in the system tray. You start and stop recording from there — no terminal, no Ctrl+C.

Recording a session

  1. Launch stepshot from the application menu → a camera icon appears in the tray.
  2. Tray icon → Start recording. The icon's dot turns red, and you get a "Recording started" notification.
  3. Click around as you normally would. Each mouse click (left / right / middle) becomes one step:
    • a screenshot of the window you clicked, with the real cursor and a red marker on the click,
    • a one-line description, e.g. “Left click on button ‘Save’ in window …”.
  4. Tray icon → Stop recording & write report. You get a "Recording stopped" notification, and the report is finalized.
  5. Tray icon → Open last report folder to view the result.

The tray tooltip and menu header show the live step count while recording.

Where recordings go

Each session is a folder:

~/Pictures/stepshot/session-<YYYY-MM-DD_HH-MM-SS>/

To use a different base folder, launch with a path argument:

stepshot ~/path/to/output

See Output and Exports for the files produced.

What gets captured

  • Only the clicked window, never the whole desktop — so the tray icon itself is never in your screenshots.
  • If the click lands on something with no visible window (the bare desktop, or KDE's transparent Xwayland video bridge), stepshot captures the whole monitor under the cursor instead, so you still see context (wallpaper, panel).
  • The report is written incrementally: if stepshot crashes or is killed mid-session, the steps captured so far are not lost.

Element descriptions

The clicked element's name comes from the accessibility tree (AT-SPI). Quality depends on the app:

  • Qt/KDE, GTK, Firefox apps usually expose element names ("button ‘Save’").
  • Apps without accessibility fall back to the window level (“… in window …”).
  • Games / canvas apps expose nothing.

See Requirements and Permissions for enabling accessibility, and Troubleshooting if names are missing.

Debug / self-test modes

Environment variables for testing without driving the tray:

STEPSHOT_ONESHOT=1 stepshot   # capture a single step right now (pipeline self-test)
STEPSHOT_DEBUG=1   stepshot   # extra diagnostics on stderr
STEPSHOT_ICON=1    stepshot   # render the tray icon to /tmp for inspection

stepshot

Repository · Releases · ROADMAP

Clone this wiki locally