Stable

garshot

Screenshot Utility

A fast X11 screenshot tool with built-in annotation editor, interactive region selection, and multiple output formats. garshot uses MIT-SHM for performance (~50ms full-screen captures) and includes 8 annotation tools with a color picker featuring HSV, RGB, and eyedropper modes.

View on GitHub Install

garshot screenshot with annotation editor

Features

MIT-SHM for fast captures (~50ms full-screen)
Built-in annotation editor with 8 tools
Color picker with HSV, RGB, palette & eyedropper
Interactive region selection with blur overlay
Window capture with optional decorations
Multiple formats: PNG, JPEG, WebP
Automatic clipboard copy via xclip/xsel
Daemon mode for instant subsequent captures
Capture delay countdown (--delay)
Desktop notification on save (--notify)
Undo/redo with full history
Multi-monitor support via XRandR

Quick Start Guide

Get up and running with garshot in just a few steps. This guide covers installation, basic usage, and essential commands.

1. Installation

Install garshot using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garshot # Install via script

$ cd ~/.local/src/gardesk/garshot && cargo build --release # Or build from source

2. System Dependencies

garshot requires X11 and optionally xclip for clipboard support:

Install dependencies

$ sudo pacman -S libx11 xclip # Arch

$ sudo apt install libx11-dev xclip # Debian/Ubuntu

$ sudo dnf install libX11-devel xclip # Fedora

3. Basic Usage

Take your first screenshots with these commands:

terminal

$ garshot # Capture full screen (default)

$ garshot region # Interactive region selection

$ garshot window # Capture active window

$ garshot screen -m HDMI-1 # Capture specific monitor

$ garshot region --delay 3 # Countdown before capture

4. Output Options

Control where screenshots go:

terminal

$ garshot -o ~/screenshot.png # Save to specific path

$ garshot -f jpeg # Use JPEG format

$ garshot --no-clipboard # Skip clipboard copy

$ garshot --notify # Show desktop notification on save

$ garshot -c # Include cursor in screenshot

5. Annotation Mode

Edit screenshots with the built-in annotation editor:

terminal

$ garshot screen --annotate # Capture + annotate

$ garshot region --annotate # Select region + annotate

$ garshot annotate screenshot.png # Annotate existing file

In the editor, use Ctrl+Enter to save or Escape to cancel.

6. Daemon Mode

Run garshot as a daemon for faster subsequent captures:

terminal

$ garshot daemon & # Start daemon in background

$ garshotctl screen # Capture via daemon

$ garshotctl region # Region select via daemon

$ garshotctl status # Check daemon status

Configuration Reference

garshot uses TOML for configuration. The config file is located at ~/.config/garshot/config.toml.

Full Configuration Example

~/.config/garshot/config.toml

[general]
# Default save directory (supports ~ expansion)
save_dir = "~/Pictures/Screenshots"

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

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

# Include cursor in screenshots by default
include_cursor = false

[selection]
# Blur radius for background during selection (pixels)
blur_radius = 15

# Selection border color (hex)
line_color = "#ff6600"

# Selection border width (pixels)
line_width = 2

[naming]
# Filename pattern with tokens:
#   %Y %m %d %H %M %S - strftime tokens
#   %N - global counter (persistent)
#   %n - daily counter (resets each day)
#   %w - window name (for window captures)
pattern = "screenshot-%Y%m%d-%H%M%S"

General Settings

Option	Default	Description
save_dir	~/Pictures/Screenshots	Default save directory
format	png	Output format
quality	90	JPEG/WebP quality (1-100)
include_cursor	false	Include cursor by default

Selection Settings

Option	Default	Description
blur_radius	15	Background blur amount
line_color	#ff6600	Selection border color
line_width	2	Selection border width

Naming Pattern Tokens

Token	Description	Example
%Y	Year (4 digits)	2026
%m	Month (01-12)	01
%d	Day (01-31)	17
%H	Hour (00-23)	14
%M	Minute (00-59)	30
%S	Second (00-59)	45
%N	Global counter	42
%n	Daily counter	5
%w	Window name	firefox

Overview

garshot is a screenshot utility designed for the gardesk desktop environment. It provides fast screen capture using MIT-SHM (shared memory), interactive region selection with a blur overlay, and flexible output options.

Architecture

garshot consists of three crates:

garshot - Main binary for captures and daemon
garshotctl - Control client for daemon communication
garshot-ipc - Shared IPC protocol types

Performance

garshot uses the MIT-SHM X11 extension for zero-copy screen capture:

~50ms for full-screen 1920x1080 capture
Instant subsequent captures in daemon mode
Fast PNG compression with Sub filter

Annotation Tools

Eight drawing tools are available via toolbar or keyboard shortcuts:

Tool	Key	Description
Arrow	A	Lines with arrowhead (default tool)
Brush	B	Freehand drawing
Line	L	Straight lines
Rectangle	R	Boxes (stroke or fill)
Ellipse	E	Circles and ovals
Text	T	Text annotations
Blur	X	Pixelate/redact regions
Highlight	H	Semi-transparent highlighter (40% opacity)

Tool Properties

Line width: Adjust with + / - keys (1-50px)
Color: Click toolbar swatch or use number keys 1-9 for presets
Fill mode: Rectangle and Ellipse can be filled or stroked

Colors

The color picker provides three ways to select colors:

HSV Tab

Hue ring around a saturation/value square. Click the ring to change hue, click the square for saturation and brightness.

RGB Tab

Sliders for Red, Green, Blue, and Alpha (0-255 each).

Palette Tab

9 preset colors (keyboard 1-9), extended palette with 36 colors, and recent colors history.

Quick Color Presets

Key	Color
1	Red
2	Orange (default)
3	Yellow
4	Green
5	Cyan
6	Blue
7	Magenta
8	White
9	Black

Eyedropper

Click the eyedropper button in the color picker to sample any color from the screen. Click to pick, Escape to cancel.

Output Formats

Format	Extension	Notes
png	.png	Lossless, fast compression (default)
jpeg	.jpg	Lossy, configurable quality
webp	.webp	Modern format, good compression
ppm	.ppm	Uncompressed, debugging/archival

$ garshot -f png # PNG (default)

$ garshot -f jpeg -q 85 # JPEG with custom quality

Naming Patterns

Customize output filenames using the [naming] section in config:

[naming]
# Examples:
pattern = "screenshot-%Y%m%d-%H%M%S"     # screenshot-20260117-143045.png
pattern = "screen-%N"                     # screen-42.png (persistent counter)
pattern = "%w-%n"                         # firefox-5.png (daily counter)
pattern = "capture-%Y-%m-%d_%H-%M-%S"     # capture-2026-01-17_14-30-45.png

If a file with the same name exists, garshot appends -1, -2, etc.

IPC Protocol

The daemon listens on a Unix socket for JSON-formatted commands.

Socket Location

$XDG_RUNTIME_DIR/garshot.sock or /tmp/garshot.sock

Request Types

{"type": "Screen", "monitor": null, "cursor": false}
{"type": "Region", "cursor": false}
{"type": "Window", "id": null, "decorations": false, "cursor": false}
{"type": "ActiveWindow", "decorations": false, "cursor": false}
{"type": "Status"}
{"type": "ListMonitors"}
{"type": "SetConfig", "key": "output_dir", "value": "/tmp"}
{"type": "ReloadConfig"}
{"type": "Shutdown"}

Response Format

// Success with file path
{"success": true, "path": "/home/user/Pictures/screenshot.png"}

// Success with base64 data (stdout mode)
{"success": true, "data": "iVBORw0KGgo..."}

// Error
{"success": false, "error": "No active window"}

garshotctl

Command-line client for controlling the garshot daemon.

Command	Description
screen [OPTIONS]	Full screen capture
region [OPTIONS]	Interactive region selection
window [OPTIONS]	Window capture
active [OPTIONS]	Active window capture
monitors	List available monitors
status	Check daemon status
shutdown	Stop the daemon

$ garshotctl screen -m eDP-1 # Capture laptop screen

$ garshotctl region -b 20 # Region with custom blur

$ garshotctl monitors # List monitors

Common Workflows

Practical examples of using garshot for everyday screenshot tasks.

Keybinding with gar

Add screenshot keybindings to your gar configuration:

~/.config/gar/init.lua

-- Screenshot keybindings
gar.bind("Print", function() gar.exec("garshot screen") end)
gar.bind("shift+Print", function() gar.exec("garshot region") end)
gar.bind("ctrl+Print", function() gar.exec("garshot window") end)
gar.bind("mod+Print", function() gar.exec("garshot screen -c") end)

-- Or using garshotctl with daemon
gar.bind("Print", function() gar.exec("garshotctl screen") end)
gar.bind("shift+Print", function() gar.exec("garshotctl region") end)

Quick Share to Clipboard

Take a screenshot and immediately paste into chat/email:

$ garshot region # Select area (auto-copied to clipboard)

$ Ctrl+V # Paste in application

Timed Screenshots

Use sleep for delayed captures:

$ sleep 5 && garshot screen # 5 second delay

$ sleep 3 && garshot region # 3 seconds then select

Batch Screenshots

Capture multiple monitors or windows in sequence:

batch-screenshots.sh

#!/bin/bash
# Capture all monitors
for monitor in $(garshot monitors | grep -oP '^S+'); do
    garshot screen -m "$monitor" -o "~/Screenshots/$monitor.png"
done

Auto-Upload Script

Upload screenshots automatically:

screenshot-upload.sh

#!/bin/bash
FILE=$(garshot region -o /tmp/screenshot.png 2>&1 | grep -oP 'Saved to: K.*')
if [ -f "$FILE" ]; then
    URL=$(curl -s -F "file=@$FILE" https://your-image-host.com/upload)
    echo "$URL" | xclip -selection clipboard
    notify-send "Screenshot uploaded" "$URL"
fi

Systemd User Service

Run garshot daemon automatically on login:

~/.config/systemd/user/garshot.service

[Unit]
Description=garshot screenshot daemon
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/local/bin/garshot daemon
Restart=on-failure

[Install]
WantedBy=default.target

$ systemctl --user enable garshot # Enable on login

$ systemctl --user start garshot # Start now

Troubleshooting

Clipboard not working

Ensure xclip is installed:

$ which xclip # Check if xclip is installed

$ sudo pacman -S xclip # Install on Arch

$ sudo apt install xclip # Install on Debian/Ubuntu

MIT-SHM error

SHM extension may not be available:

$ xdpyinfo | grep MIT-SHM # Check SHM support

If running over SSH, use -X (not -Y) or consider running garshot locally.

garshotctl: connection refused

The daemon may not be running:

$ pgrep -x garshot # Check if daemon is running

$ ls -la ${XDG_RUNTIME_DIR:-/tmp}/garshot.sock # Check socket exists

$ garshot daemon & # Start daemon

Selection overlay not appearing

Check DISPLAY environment:

$ echo $DISPLAY # Should show :0 or similar

$ DISPLAY=:0 garshot region # Explicitly set display

Monitor not found

Verify monitor name with xrandr:

$ xrandr --query | grep " connected" # List connected monitors

$ garshot monitors # List monitors known to garshot

Use the exact name shown (e.g., HDMI-1 not hdmi-1).

Cursor not appearing in screenshot

XFixes extension may not be available:

$ xdpyinfo | grep XFIXES # Check XFixes support

$ garshot -c screen # Explicitly request cursor

Screenshots save with wrong permissions

Check umask settings:

$ umask # Check current umask

$ chmod 644 ~/Pictures/Screenshots/*.png # Fix permissions

Debug logging

Enable verbose output:

$ RUST_LOG=debug garshot screen # Debug mode

$ RUST_LOG=trace garshot region # Trace mode (very verbose)

Back to home

-m, --monitor	Monitor name (e.g., HDMI-1, eDP-1)
-c, --cursor	Include cursor in capture
-o, --output	Output file path
-f, --format	Output format (png, jpeg, webp)

-b, --blur	Blur radius (default: 15)
-c, --cursor	Include cursor in capture
--no-clipboard	Skip clipboard copy

-i, --id	Window ID (hex 0x... or decimal)
-d, --decorations	Include WM decorations/frame
-c, --cursor	Include cursor if visible

Ctrl+Enter	Save and close
Escape	Cancel (if not editing text)
Ctrl+Z	Undo
Ctrl+Shift+Z / Ctrl+Y	Redo

Click	Start typing at position
Return	Finish text entry
Backspace	Delete character
Escape	Cancel text entry

+ or =	Increase width (max 50px)
-	Decrease width (min 1px)

garshot

Features

Quick Start Guide

1. Installation

2. System Dependencies

3. Basic Usage

4. Output Options

5. Annotation Mode

6. Daemon Mode

Configuration Reference

Full Configuration Example

General Settings

Selection Settings

Naming Pattern Tokens

Overview

Architecture

Performance

Capture Modes

Screen Capture

Options

Region Capture

Controls

Options

Window Capture

Options

Finding Window IDs

Active Window Capture

Annotations

Annotation Tools

Tool Properties

Colors

HSV Tab

RGB Tab

Palette Tab

Quick Color Presets

Eyedropper

Keyboard Shortcuts

Global

Tool Selection

Line Width

Text Tool

Output

Output Formats

Clipboard

Naming Patterns

Daemon Mode

IPC Protocol

Socket Location

Request Types

Response Format

garshotctl

Selection UI

How It Works

Technical Details

Multi-Monitor Support

Monitor Info

Common Workflows

Keybinding with gar

Quick Share to Clipboard

Timed Screenshots

Batch Screenshots

Auto-Upload Script

Systemd User Service

Troubleshooting

Clipboard not working

MIT-SHM error

garshotctl: connection refused

Selection overlay not appearing

Monitor not found

Cursor not appearing in screenshot

Screenshots save with wrong permissions

Debug logging