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.
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 easyshotStart 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.serviceThen ask easyshot what your desktop supports. It lists each capability, which provider it chose and why, and any tool that is missing.
$ easyshot doctorsystemctl --user mask --now easyshot.service. A plain disable does not override the package.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.
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"))| Action | Command |
|---|---|
| Capture an area | easyshot capture region |
| Capture the whole screen | easyshot capture fullscreen |
| Capture the previous area, window or display again | easyshot capture previous |
| Open or close the capture bar | easyshot capture-bar |
| Record the screen | easyshot record |
| Capture text (OCR) | easyshot ocr |
| Pick a colour | easyshot color-picker |
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 regionWindow
Hover to highlight a window, click to take it.
easyshot capture windowFull screen
The output under the pointer.
easyshot capture fullscreenTimed
Pick first, then a countdown runs and a fresh frame is taken. Add --timed to region, window or fullscreen.
easyshot capture window --timed 5Scrolling
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 scrollText
Reads the text, or a QR code, in an area and copies it.
easyshot ocrAnnotate 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.
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 cardThe 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.
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.
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
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 enableWhen 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.
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 --projectIt 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 mcpAdd --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 --jsonRevoke 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.
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.