Hermes Agent vision: send it screenshots and images

Getting an image into the conversation

In the CLI, copy an image and either paste it or type /paste. Each attached image shows up as a badge above the input. You can attach several before sending, and Ctrl+C clears them. Terminals can't send raw image bytes, so if your clipboard holds only an image and pasting does nothing, use /paste, which reads the clipboard directly. Attached images are saved as PNG files under ~/.hermes/images/.

From your phone, just send the photo to your bot on Telegram, Discord, Slack or WhatsApp. These platforms handle the upload themselves, so none of the clipboard limitations below apply. You can also paste an image URL into a message, and the agent can look at it with the vision_analyze tool.

Clipboard setup by platform

• macOS: works out of the box using osascript. Installing pngpaste makes it faster.
• Linux on X11: install xclip. On Wayland: install wl-clipboard. Run echo $XDG_SESSION_TYPE to find out which one you're using.
• WSL2: no install needed. Hermes reads the Windows clipboard through powershell.exe.
• Over SSH: clipboard images don't work, because the clipboard tools read the remote machine's clipboard, not yours. Copy the file over with scp and reference it by path, use a URL, or send the image through a messaging app.

Vision models and text-only models

You don't need to choose a special model for images to work. If the current model supports vision, Hermes sends the actual pixels. If it doesn't, the image goes through vision_analyze, where an auxiliary vision model describes it and the description is added to the conversation. This happens automatically, so you can switch models mid-session without changing how you work. Browser screenshots, computer-use captures and MCP image results all follow the same rule.

To override the automatic choice, set agent.image_input_mode to native (always send pixels), text (always send a description) or leave it on auto. The documented reason to change it is a backend that accepts text but rejects image input. In that case, keep your main model and point auxiliary.vision at a different vision-capable provider and model. In auto mode, an explicitly configured auxiliary.vision backend already switches images to the description path.

Keeping image-heavy sessions affordable

An image embedded natively is re-sent with every later request in the session, so it keeps costing tokens. Two settings limit that. vision.embed_target_bytes (default 256 KB) downscales large images to fit. Raise it, for example to 1048576, if dense screenshots of tables come back unreadable. vision.max_calls_per_image caps how often the same image can be embedded. By default only delegated subagents are capped, at 3, but you can set a number for every session.

vision.replay_recent_images (default 3) re-sends your most recent images when a session is rebuilt from history, for example after a resume or a gateway restart, so a follow-up question about a photo still sees it. Set it to 0 to turn that off. On the gateway, the stored copy of a chat image is cleaned up after 24 hours, so a question about a photo from yesterday may only see a [screenshot] placeholder. Send the image again if it matters.

A quick checklist when an image is ignored

• No badge appeared: use /paste, and install xclip or wl-clipboard on Linux.
• Working over SSH: transfer the file, or use a messaging app instead.
• The model says it can't see images: check agent.image_input_mode and your auxiliary.vision settings.
• The model only sees an [image omitted ...] note for an SVG, BMP or TIFF on a Responses-style backend such as openai-codex: those backends accept only JPEG, PNG, GIF and WebP. Hermes converts SVGs to PNG when a rasterizer such as rsvg-convert or cairosvg is installed. Other formats need converting before you send them.

Related guides

• How to choose a model for Hermes Agent
• How to keep Hermes Agent costs down
• Hermes Agent messaging gateway explained

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher