Usage

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 translucent yellow highlight on the click (text under it stays readable),
   • 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

• The clicked window by default — screenshots show exactly the window you worked in.
• Clicks that don't land in the active window — the panel/taskbar, the start menu button, the bare desktop — capture the whole monitor under the cursor instead, so the thing you clicked is in the picture (since alpha.3).
• Clicks inside popup menus (context menus, dropdowns) also get a full-screen capture: popups are separate Wayland surfaces and would be invisible in a window capture of their parent (since alpha.3). Such steps are described as "(full-screen view)".
• stepshot's own clicks stay out: the clicks that operate the tray menu (start/stop/quit) are not recorded as steps (since alpha.3).
• 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_ATTREE=3  stepshot   # dump the AT-SPI tree (to the given depth)
STEPSHOT_ATDUMP=1  stepshot   # find the first named button and resolve it back

stepshot --help and stepshot --version work as expected.