Skip to content

From install to your first screenshot.

Nine short steps, and a tenth if you use an AI agent. About ten minutes, most of it spent choosing which keys to use.

Hyprlandswayniri
1

Check what you need

A Wayland compositor

Hyprland 0.57+, sway 1.12 or niri 26.04 (built for niri, not tested on it). Others with layer-shell and a capture protocol work for basic capture. Not KDE or GNOME.

Tesseract (optional)

For text capture (OCR) and Smart Redaction. Install the English data too, for example tesseract-data-eng.

A recorder (optional)

gpu-screen-recorder (preferred) or wf-recorder for recording; ffmpeg for trimming and export. To play videos in the trim viewer: GStreamer good plugins and gst-libav. To record a window from its own picture: also an H.264 parser and encoder.

2

Install easyshot

Pick your distribution. The package installs the app and the easyshot command, and enables the background service.

Arch Linux. Two packages: easyshot builds from source, easyshot-bin is prebuilt. Install one.

# with an AUR helper
$ yay -S easyshot-bin
# or build it from source
$ yay -S easyshot
3

Start the service

easyshot runs as one background service, easyshot.service, with a tray icon. The package starts it for you. Built from source, start it yourself; your first command also starts it through D-Bus.

$ systemctl --user enable --now easyshot.service

Then ask easyshot what your desktop supports. It lists each capability, which provider it chose and why, and any tool that is missing.

$ easyshot doctor
To stop it starting for your user, run systemctl --user mask --now easyshot.service. A plain disable does not override the package.
4

Bind your keys

Wayland apps cannot grab global keys, so your compositor binds them, and easyshot sets none until you choose. On first run, Set your shortcuts suggests keys; later, use Settings › Shortcuts. easyshot writes your keys to its own file in ~/.config/easyshot/ and keeps it up to date. You add one line to your compositor config, once, and press Copy Line to get it. Check shows whether it is Included. easyshot never edits your config. The file it writes looks like the lines below, for example.

~/.config/easyshot/binds.lua
hl.bind("SUPER + SHIFT + 4", hl.dsp.exec_cmd("easyshot capture region"))
hl.bind("SUPER + SHIFT + 3", hl.dsp.exec_cmd("easyshot capture fullscreen"))
hl.bind("SUPER + SHIFT + 1", hl.dsp.exec_cmd("easyshot capture previous"))
hl.bind("SUPER + SHIFT + 2", hl.dsp.exec_cmd("easyshot capture-bar"))
hl.bind("SUPER + SHIFT + 5", hl.dsp.exec_cmd("easyshot record"))
hl.bind("SUPER + SHIFT + O", hl.dsp.exec_cmd("easyshot ocr"))
hl.bind("SUPER + SHIFT + C", hl.dsp.exec_cmd("easyshot color-picker"))
Global actions you can bind
Action
Capture an area
Capture the whole screen
Capture the previous area, window or display again
Open or close the capture bar
Record the screen
Capture text (OCR)
Pick a colour
Press Check in Settings › Shortcuts to see which keys are already bound in your compositor.
5

Take a screenshot

Press the key you bound to easyshot capture region. The screen freezes, you drag an area, and the capture lands as a card in the preview deck, where you can copy, save, edit, pin or drag it into another app or a file manager. Once auto-save has saved it, Save becomes Show in Folder. Several captures stack up in the corner; hover the stack to fan the cards out.

Area

Drag a selection on the frozen screen and adjust it. Press Space to switch to window mode. Add --copy, --save, --annotate or --pin to choose what happens next.

easyshot capture region

Window

Hover to highlight a window, click to take it.

easyshot capture window

Full screen

The output under the pointer.

easyshot capture fullscreen

Timed

Pick first, then a countdown runs and a fresh frame is taken. Add --timed to region, window or fullscreen.

easyshot capture window --timed 5

Scrolling

Draw the area to scroll, or press Space to pick a window, then scroll by hand or with Auto Scroll where your compositor allows it. easyshot joins it into one tall image, with fixed top and bottom bars shown once, a minimap or side panel kept as the first view showed it and a scrollbar at the right edge cut off, even on pages with a playing video. Press the shortcut again, or Stop, to finish.

easyshot capture scroll

Text

Reads the text, or a QR code, in an area and copies it.

easyshot ocr
6

Annotate and export

Click a deck card or choose Edit on it, or capture with --annotate. Add arrows, shapes, text and steps, with each tool's options (colour, stroke, arrowheads, font) in the inspector, blur what is private with Smart Redaction (it says what it hid and offers Undo), highlight text with the Highlighter, then set a background, padding, shadow and canvas shape in the inspector on the right. Save keeps your edits editable; Export writes PNG or JPEG.

Nudge by 1 px (Shift: 10 px)Arrowkeys
Highlighter; press again to switch freehand and straight (Shift snaps to 15°)M
Duplicate the selectionCtrlD
Copy the imageCtrlShiftC
Pan the canvasSpace+drag
Zoom about the pointer (two-finger touchpad scroll pans)Mousewheel
Select the next shapeTab
Smart Redaction only covers text Tesseract can read. Look over the result before you share.
7

Record your screen

Press the key you bound to easyshot record and pick an area, a display or a window. The recording panel lists every open window by workspace, with its app's icon and title. System sound is recorded unless you turn it off, and the microphone once you choose one, as two separate tracks. After the countdown a small bar lets you stop, mute each sound, pause, start over or discard.

$ easyshot record          # start
$ easyshot record stop     # stop; the recording lands as a deck card

The recording appears as a deck card and opens in the trim viewer, where you cut it, set a volume for each track and export MP4, WebM or GIF. Saved recordings and exports go to ~/Videos/easyshot/. One recording runs at a time. Where your compositor allows it, a window recording follows that window itself, so it still shows the window when something covers it or it is on another workspace.

8

Share a link

Press Share on a capture's card, in the editor or in the trim viewer. Give the link a title if you like, press Share (Enter works too); with easyshot Free you also pick how long it lasts, 1, 3 or 7 days. The link is copied at once, and a toast shows the upload with Cancel, then Open and Copy Link. A card with a live link carries a small cloud mark.

There is no destination to choose and no first-share step: pressing Share is the consent. Shares go to easyshot Free by default, and to your own bucket once you set it up in Settings › Sharing. The days choice shows only for easyshot Free.

easyshot Free

The default: no account and no setup. Images up to 10 MB, GIFs up to 20 MB, and videos up to 200 MB, re-encoded to fit (roughly 13 to 27 minutes of 1080p screen recording), with a daily allowance for each install. After the days you pick, the file is deleted.

Your own bucket

Used once you set it up in Settings › Sharing: any S3-compatible storage, such as Cloudflare R2, AWS S3, Backblaze B2 or MinIO. Fill in its endpoint, bucket, public URL and keys, and press Test Connection. Keys go to your keyring, or a private file. Links last as long as you keep the files.

The link opens a page with the image or video, sized to your screen, and Download and Copy link; View full size, or a click on the image, shows it across the whole window. In the gallery, a shared item shows a cloud mark with the time left, Cloud Shares in the sidebar lists every link, and Delete Cloud Share takes one down while your file stays. After a free link expires, visitors see “page not found” and only you see Expired. To share from a terminal, run the command below; it prints the link.

$ easyshot share shot.png --days 3
Share links are unlisted, not private: anyone who has a link can open it. Free shares follow the Terms of Service.
9

Settings and files

Easyshot in your app menu, or easyshot on its own, opens the Home window: your media gallery and Settings, one tab each. The tray's Settings item and easyshot settings open it on Settings. Every change applies at once. You can also edit config.toml by hand: easyshot watches it and applies changes live.

AI agents and scripts can use easyshot agent to capture, read text, record and annotate. Step 10, Use it from an AI agent, sets it up.
Settings
~/.config/easyshot/config.toml
Screenshots
~/.local/share/easyshot/library/
Recordings
~/.local/share/easyshot/recordings/
Logs and crash reports
~/.local/state/easyshot/log/
Default save folder
~/Pictures/Screenshots
Saved recordings and exports
~/Videos/easyshot/
Your keys (binds file)
~/.config/easyshot/binds.conf, binds.lua or binds.kdl
10

Use it from an AI agent

easyshot agent (or easyshot ai) lets an AI agent or a script list your outputs and windows, take screenshots, read text and QR codes, annotate an image, and record a short demo and export it. With --json each command prints exactly one JSON object, errors included, and each kind of error has its own exit code.

Turn agent access on

Agent access is off until you turn it on, in Settings › Agents or with the command below. easyshot asks you first in a “Turn on agent access?” dialog. easyshot agent status shows whether it is on and what is allowed.

$ easyshot agent enable

When an agent then asks for something, a dialog names the program and what it wants. You can allow it for 1 hour, until you log out, or always, or deny it; Esc, closing the dialog or leaving it for 60 seconds denies. By default it asks once per session. Set consent to always-ask to be asked every time, or always-allow to never be asked.

To limit agents to some outputs or windows, list their output names in allowed_outputs and their app ids in allowed_windows; both are empty by default, which allows everything. Only your own user can send agent commands, and nothing goes over the network.

While redact_secrets is on, as it is by default, secrets are covered in every agent screenshot: API keys and tokens, passwords, emails, links, IP addresses, phone and card numbers. This uses Tesseract and is a best effort; small, low-contrast or rotated text can be missed.

Install the skill

The skill is a short guide that teaches your agent to use easyshot agent: to check access first, to ask you rather than turn it on itself, and to treat text read from the screen as data, not instructions.

$ easyshot agent skill install
# or into the current folder, to commit with a project
$ easyshot agent skill install --project

It writes the skill to ~/.agents/skills/easyshot/, which Codex, Gemini CLI and Cursor read, and links ~/.claude/skills/easyshot to it for Claude Code. --project writes .agents/skills/easyshot/ and .claude/skills/easyshot in the current folder instead. Start a new agent session afterwards, since clients read their skills when they start.

Or add the MCP server

easyshot agent mcp is a Model Context Protocol server, for agents that prefer tools to shell commands. Access, consent, scope and covered secrets work as they do for the commands. Register it with your client:

$ claude mcp add easyshot -- easyshot agent mcp

Add --scope project to write .mcp.json for a project.

It offers list_outputs, list_windows, capture, ocr, record_start, record_stop, export, annotate. capture returns the screenshot itself, scaled to at most 1280 pixels on its long edge, and the path of the full file.

Try it

Ask your agent in plain words, for example:

  • Take a screenshot of my editor window and tell me what the error says.
  • Read the QR code on my screen.
  • Record a 20-second demo of the app in Firefox and export it as a GIF.

Or run the same from a terminal:

$ easyshot agent list windows --json
$ easyshot agent capture --window firefox --json
$ easyshot agent ocr --window firefox --json
$ easyshot agent record start --window firefox --max-seconds 20 --json
$ easyshot agent record stop --json
# export the video that record stop printed as a GIF
$ easyshot agent export ~/Videos/easyshot/demo.mp4 --format gif --json

Revoke access

While a grant is in force the tray icon carries a badge, and the tray menu has a row such as “Agent access until 14:05 — Revoke” that ends it in one click. easyshot agent disable turns access off and ends every grant. A recording an agent started stops, and is kept, when its access ends.

Troubleshooting

If something is not right

Start with easyshot doctor. Set EASYSHOT_LOG to change what is logged.

Run the command from a terminal, for example easyshot capture region. If it says the daemon is not running, start it with systemctl --user start easyshot.service. Then check that the bind line is in your compositor config and reload it.

A tool is missing. Install gpu-screen-recorder or wf-recorder for recording, or Tesseract for text; QR codes are read without it. easyshot doctor lists what is missing.

Your compositor does not report window positions. Pick the window from the list; the capture is the same.

Your compositor hides the pointer when you press a key, until you move the mouse. On Hyprland turn off cursor:hide_on_key_press; on sway, seat * hide_cursor when-typing disable.

easyshot keeps running on the last good settings, never overwrites your file, and tells you the line and column. Fix it and save; changes apply live.

The next start offers “Open crash report”. Run easyshot doctor --bundle to make a report with your logs (no images), look it over, and attach it to an issue.

Still stuck? Read the full manual or open an issue.