StepSnap usage guide

Install

StepSnap runs on Windows, macOS, and Linux (X11 and Wayland). Use a virtual environment to keep dependencies isolated.

On Debian or Ubuntu install the evdev system library first. Arch users take python-evdev from pacman.

git clone https://github.com/pdev-labs/StepSnap.git
cd StepSnap
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Record

Run the recorder and work normally. Every click and Enter keypress captures a screenshot with a one-second throttle against double-clicks.

Press F9 any time to pause and resume. Name the session up front or accept the timestamped default folder.

As you work, StepSnap appends each step to steps.md, ready to paste straight into a pull request or issue.

Note: Screenshots can capture tokens and private tabs. Review the folder before posting it anywhere public. On Wayland the process needs input group membership for evdev.

python stepsnap.py

Publish

Open steps.md, check the images in order, and paste the whole file into GitHub. Relative image paths resolve once the folder ships alongside the Markdown.

For tutorials, record once per feature and keep the raw folders. Re-recording a single changed step beats re-recording everything.

Platform notes

Windows and macOS need no special setup. Run the script and grant screen-recording permission if the OS asks on first capture.

Linux X11 works out of the box. On Wayland the process must read the input devices, so join the input group and log back in if captures come out empty.

Lower the throttle interval in config when documenting fast click sequences, and raise it for long reading sessions to keep folders small.