✓ Stable v0.1.0

garshot

X11 screenshot utility with annotation editor

garshot is a screenshot utility for the gardesk ecosystem featuring fast MIT-SHM capture, interactive selection with blur overlay, multi-monitor support via XRandR, built-in annotation editor with 8 drawing tools, and multiple output formats including PNG, JPEG, and WebP. Supports daemon mode with IPC for quick captures.

View on GitHub Download RPM

🎯 RPM Available

Installation

garshot is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garshot

Building from Source

$git clone https://github.com/espadon/gardesk

$cd gardesk/garshot

$cargo build --release

$sudo install -Dm755 target/release/garshot /usr/local/bin/garshot

$sudo install -Dm755 target/release/garshotctl /usr/local/bin/garshotctl

Build Dependencies

$sudo dnf install libxcb-devel libX11-devel cairo-devel# Fedora/RHEL

$sudo apt install libxcb1-dev libx11-dev libcairo2-dev# Debian/Ubuntu

$sudo pacman -S libxcb libx11 cairo# Arch Linux

Runtime Dependencies

xclip - Clipboard integration (or xsel as fallback)
libnotify - Desktop notifications (optional, for --notify)

Quick Start

Full Screen Capture

Capture the entire screen and save to the default directory:

$garshot screen

~/Pictures/Screenshots/screenshot-20260203-143052.png

Interactive Selection

Click and drag to select a region with blur overlay:

$garshot select# Opens selection overlay

Controls: Left click + drag to select, release to capture, right click or Escape to cancel.

Window Capture

$garshot window# Capture active window

$garshot window -d# Include window decorations

$garshot window -i 0x1400007# Capture by window ID

Region by Geometry

$garshot region -g 800x600+100+50# WxH+X+Y format

Capture with Annotation

Open the annotation editor immediately after capture:

$garshot screen -a# Capture and annotate

$garshot select -a# Select region and annotate

$garshot annotate ~/Pictures/screenshot.png# Edit existing file

gar Keybindings

Add to ~/.config/gar/init.lua:

-- Screenshot keybindings
gar.bind("ctrl+shift+4", function()
    gar.exec("garshot select")
end)

gar.bind("ctrl+shift+5", function()
    gar.exec("garshot screen")
end)

gar.bind("ctrl+shift+6", function()
    gar.exec("garshot window")
end)

-- With annotation editor
gar.bind("ctrl+shift+3", function()
    gar.exec("garshot select -a")
end)

Common Options

Option	Type	Default	Description
`-o, --output PATH`	-	Auto-generated	Output file path (use "-" for stdout)
`-f, --format FMT`	-	png	Output format: png, jpeg, webp
`-c, --cursor`	-	false	Include mouse cursor in capture
`--no-clipboard`	-	false (copies)	Skip copying to clipboard
`--delay SECS`	-	none	Countdown delay before capture
`--notify`	-	false	Show desktop notification on save
`-a, --annotate`	-	false	Open annotation editor after capture

Configuration

garshot uses TOML configuration at ~/.config/garshot/config.toml.

Minimal Configuration

[general]
save_dir = "~/Pictures/Screenshots"
format = "png"

[selection]
blur_radius = 15

Full Configuration

[general]
# Screenshot save directory (tilde expansion supported)
save_dir = "~/Pictures/Screenshots"

# Default output format: png, jpeg, webp, ppm
format = "png"

# JPEG/WebP quality (1-100)
quality = 90

# Include cursor in screenshots by default
include_cursor = false

[selection]
# Blur radius for selection overlay (higher = more blur)
blur_radius = 15

# Selection rectangle color (#RRGGBB)
line_color = "#ff6600"

# Selection rectangle line width in pixels
line_width = 2

[naming]
# Filename pattern with strftime tokens
# %Y=year, %m=month, %d=day, %H=hour, %M=minute, %S=second
pattern = "screenshot-%Y%m%d-%H%M%S"

General Settings

Option	Type	Default	Description
`save_dir`	path	~/Pictures/Screenshots	Directory to save screenshots
`format`	string	"png"	Default output format: png, jpeg, webp, ppm
`quality`	u8	90	JPEG/WebP compression quality (1-100)
`include_cursor`	bool	false	Include mouse cursor in captures by default

Selection Overlay Settings

Option	Type	Default	Description
`blur_radius`	usize	15	Blur radius for selection overlay background
`line_color`	string	"#ff6600"	Selection rectangle color (hex: #RRGGBB)
`line_width`	u32	2	Selection rectangle line width in pixels

File Naming Settings

Option	Type	Default	Description
`pattern`	string	"screenshot-%Y%m%d-%H%M%S"	Filename pattern with strftime tokens

Strftime Tokens

Option	Type	Default	Description
`%Y`	-	2026	Four-digit year
`%m`	-	02	Two-digit month (01-12)
`%d`	-	03	Two-digit day (01-31)
`%H`	-	14	Two-digit hour (00-23)
`%M`	-	30	Two-digit minute (00-59)
`%S`	-	52	Two-digit second (00-59)

Output Formats

PNG - Lossless compression, best for screenshots with text and UI elements
JPEG - Lossy compression with configurable quality, good for photo-like content
WebP - Modern format with good compression for both lossless and lossy modes
PPM/PAM - Uncompressed formats for maximum compatibility and piping

$garshot screen -f png# Lossless PNG (default)

$garshot screen -f jpeg# JPEG with quality from config

$garshot screen -f webp# WebP format

$garshot screen -f ppm -o - | convert - processed.png# Pipe to ImageMagick

Environment Variables

Option	Type	Default	Description
`RUST_LOG`	-	info	Logging level: error, warn, info, debug, trace
`XDG_RUNTIME_DIR`	-	/run/user/UID	Directory for daemon socket
`XDG_CONFIG_HOME`	-	~/.config	Config directory base

Overview

garshot is an X11 screenshot utility designed for the gar desktop environment. It provides fast screen capture using MIT-SHM, an interactive selection overlay with blur effect, and a built-in annotation editor with drawing tools.

Key Features

MIT-SHM capture - Shared memory for fast screen capture
Multi-monitor support - Via XRandR with per-monitor capture
Interactive selection - Blur overlay with dimension display
Annotation editor - 8 drawing tools with color picker
Multiple formats - PNG, JPEG, WebP, PPM/PAM
Clipboard integration - Automatic copy via xclip/xsel
Daemon mode - Persistent process with IPC for fast captures

Annotation Editor

garshot includes a built-in annotation editor for drawing on screenshots. The editor opens automatically with the -a flag or when using the annotate command.

Opening the Editor

$garshot screen -a# Capture and annotate

$garshot select -a# Select region and annotate

$garshot annotate image.png# Annotate existing file

Editor Interface

Toolbar - Tool buttons at top (48px height)
Canvas - Screenshot with annotations
Color preview - Current color swatch
Line width indicator - Current stroke width

Saving and Cancelling

Ctrl+Enter - Save annotated image
Escape - Cancel without saving

Drawing Tools

Option	Type	Default	Description
`b`	-	-	Brush - freehand drawing
`l`	-	-	Line - straight line
`a`	-	-	Arrow - line with arrowhead
`r`	-	-	Rectangle - outlined or filled rectangle
`e`	-	-	Ellipse - outlined or filled ellipse
`t`	-	-	Text - add text annotation
`x`	-	-	Blur - blur region of screenshot
`h`	-	-	Highlight - semi-transparent highlight

Brush Tool (B)

Freehand drawing with configurable stroke width and color.

Click and drag to draw
Use +/- to adjust line width
Smooth antialiased strokes via Cairo

Line Tool (L)

Draw straight lines between two points.

Click to set start point
Drag to see preview
Release to commit line

Arrow Tool (A)

Draw lines with arrowheads - the default tool.

Arrow points toward release position
Arrowhead size scales with line width (4x multiplier)
30-degree wing angle for balanced appearance

Rectangle Tool (R)

Draw rectangles with optional fill.

Click and drag from corner to corner
Outlined by default (stroke only)
Toggle fill mode for solid rectangles

Ellipse Tool (E)

Draw ellipses and circles.

Click and drag to define bounding box
Outlined by default

Text Tool (T)

Add text annotations to screenshots.

Click to place text cursor
Type to enter text
Configurable font size (default 16px)
Uses system monospace font

Blur Tool (X)

Blur sensitive information in screenshots.

Click and drag to define blur region
Configurable blur radius (default 15px)
Gaussian blur applied to region

Highlight Tool (H)

Semi-transparent highlight for emphasis.

Click and drag to highlight region
Uses current color with reduced opacity
Multiple highlights can overlap

Keyboard Shortcuts

Tool Selection

Option	Type	Default	Description
`b`	-	-	Brush - freehand drawing
`l`	-	-	Line - straight line
`a`	-	-	Arrow - line with arrowhead
`r`	-	-	Rectangle - outlined or filled rectangle
`e`	-	-	Ellipse - outlined or filled ellipse
`t`	-	-	Text - add text annotation
`x`	-	-	Blur - blur region of screenshot
`h`	-	-	Highlight - semi-transparent highlight

Color Presets (1-9)

Option	Type	Default	Description
`1`	-	-	Red (#ff0000)
`2`	-	-	Orange (#ff6600)
`3`	-	-	Yellow (#ffff00)
`4`	-	-	Green (#00ff00)
`5`	-	-	Cyan (#00ffff)
`6`	-	-	Blue (#0000ff)
`7`	-	-	Magenta (#ff00ff)
`8`	-	-	White (#ffffff)
`9`	-	-	Black (#000000)

Line Width

Option	Type	Default	Description
`+`	-	-	Increase line width (max 50px)
`-`	-	-	Decrease line width (min 1px)

Actions

Option	Type	Default	Description
`Ctrl+Enter`	-	-	Save annotated image and exit
`Escape`	-	-	Cancel annotation and exit
`Ctrl+Z`	-	-	Undo last annotation (planned)

Daemon Mode

garshot can run as a background daemon for faster capture response. The daemon keeps X11 connections open and pre-allocates shared memory.

Starting the Daemon

$garshot daemon# Run in foreground

$garshot daemon &# Run in background

Socket created at $XDG_RUNTIME_DIR/garshot.sock

Using garshotctl

$garshotctl screen# Capture full screen

$garshotctl screen -m DP-1# Capture specific monitor

$garshotctl region# Interactive selection

$garshotctl window# Capture active window

$garshotctl active -d# Active window with decorations

$garshotctl monitors# List available monitors

$garshotctl status# Show daemon status

$garshotctl shutdown# Stop the daemon

IPC Protocol

Communication uses JSON over Unix socket with newline-delimited messages.

Request Examples

{"command": "screen", "monitor": "DP-1", "cursor": true, "output": "file"}
{"command": "region", "cursor": false, "output": "clipboard"}
{"command": "window", "id": 20971527, "decorations": true}
{"command": "active_window", "decorations": false}
{"command": "status"}
{"command": "list_monitors"}
{"command": "shutdown"}

IPC Commands

Option	Type	Default	Description
`screen`	-	-	Capture full screen or specific monitor
`region`	-	-	Interactive region selection
`window`	-	-	Capture specific window by ID
`active_window`	-	-	Capture currently focused window
`status`	-	-	Get daemon status information
`list_monitors`	-	-	List available monitors
`set_config`	-	-	Update configuration value at runtime
`reload_config`	-	-	Reload configuration from disk
`shutdown`	-	-	Graceful daemon shutdown

Output Modes

Option	Type	Default	Description
`file`	-	-	Save to file (default)
`stdout`	-	-	Output raw image data to stdout
`clipboard`	-	-	Copy to clipboard only
`file_and_clipboard`	-	-	Save to file and copy to clipboard

Response Examples

// Successful capture
{"success": true, "path": "/home/user/Pictures/Screenshots/screenshot.png"}

// Clipboard only
{"success": true}

// Error
{"success": false, "error": "No window with ID 0x1400007"}

// Status response
{"success": true, "info": {"uptime": 3600, "captures": 42}}

// Monitor list
{"success": true, "info": [
  {"name": "DP-1", "width": 1920, "height": 1080, "x": 0, "y": 0, "primary": true}
]}

Socket Communication Example

$echo '{"command": "screen"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/garshot.sock

Daemon vs One-Shot

Option	Type	Default	Description
`Startup time`	-	-	Daemon: ~50ms (IPC) vs One-shot: ~200ms (X11 connect + SHM alloc)
`Memory usage`	-	-	Daemon: Persistent ~20MB vs One-shot: Temporary
`Best for`	-	-	Daemon: Frequent captures, hotkeys vs One-shot: Scripts, occasional use

Common Issues

Clipboard Copy Fails

Symptom: "No clipboard tool available" error.

Solution: Install xclip or xsel:

$sudo dnf install xclip# Fedora/RHEL

$sudo apt install xclip# Debian/Ubuntu

Selection Overlay Doesn't Appear

Symptom: garshot select hangs or shows nothing.

Causes and solutions:

Compositor conflict - Try disabling compositor effects temporarily
Pointer grab failed - Close any modal dialogs or menus
X11 display issue - Ensure DISPLAY is set correctly

Black Screenshots

Symptom: Screenshots are completely black.

DRM-protected content - Video players may use DRM that prevents capture
Hardware overlay - Some video playback uses hardware overlays not visible to X11
Compositor issue - When a compositor is active with alpha=0, garshot forces opaque alpha

Daemon Socket Not Found

Symptom: "Daemon not running" error from garshotctl.

$garshot daemon &# Start the daemon

$ls $XDG_RUNTIME_DIR/garshot.sock# Verify socket exists

Cursor Not Captured

Solution: Use the -c or --cursor flag:

$garshot screen -c# Include cursor

Or set include_cursor = true in config.

Window Decorations Missing

Solution: Use the -d flag to include decorations:

$garshot window -d# Include decorations

Blur Too Slow

Solutions:

Reduce blur_radius in config (try 10 instead of 15)
The blur is a one-time cost when selection starts

Format Not Supported

Supported formats: png, jpeg (jpg), webp, ppm, pam

$garshot screen -f png# PNG (default)

$garshot screen -f jpeg# JPEG

$garshot screen -f webp# WebP

Debug Logging

$RUST_LOG=debug garshot screen# Debug level

$RUST_LOG=trace garshot select# Maximum verbosity

Reporting Issues

When reporting issues, please include:

garshot version: garshot --version
Distribution and version: cat /etc/os-release
X11 server info: xdpyinfo | head -5
Debug output: RUST_LOG=debug garshot [command] 2>&1
Compositor in use (picom, compton, etc.)

Report issues at GitHub Issues.

garshot

Installation

Using DNF (Recommended)

Building from Source

Build Dependencies

Runtime Dependencies

Quick Start

Full Screen Capture

Interactive Selection

Window Capture

Region by Geometry

Capture with Annotation

gar Keybindings

Common Options

Configuration

Minimal Configuration

Full Configuration

General Settings

Selection Overlay Settings

File Naming Settings

Strftime Tokens

Output Formats

Environment Variables

Overview

Key Features

Architecture

Capture Engine

MIT-SHM Capture

Selection Overlay

Encoding Pipeline

Capture Modes

Full Screen Capture

Full Screen Capture

Window Capture

Region by Geometry

Interactive Selection

Multi-Monitor Support

XRandR Integration

Monitor Selection

Output Handling

File Output

Clipboard Copy

Stdout Pipe

Annotation Editor

Opening the Editor

Editor Interface

Saving and Cancelling

Drawing Tools

Brush Tool (B)

Line Tool (L)

Arrow Tool (A)

Rectangle Tool (R)

Ellipse Tool (E)

Text Tool (T)

Blur Tool (X)

Highlight Tool (H)

Color Picker

HSV Color Wheel

RGB Sliders

Palette & Recent Colors

Eyedropper

Keyboard Shortcuts

Tool Selection

Color Presets (1-9)

Line Width

Actions

Daemon Mode

Starting the Daemon

Using garshotctl

IPC Protocol

Request Examples

IPC Commands

Output Modes

Response Examples

Socket Communication Example

Daemon vs One-Shot

Common Issues

Clipboard Copy Fails

Selection Overlay Doesn't Appear

Black Screenshots