| name | flashpaste |
| description | Use when the user wants to take a screenshot, paste an image into a terminal AI agent (Claude Code, Codex, Aider), hand content off between tmux panes, or debug clipboard issues on GNOME Wayland. flashpaste provides one unified CLI (`flashpaste shoot`, `flashpaste paste`, `flashpaste daemon`, `flashpaste doctor`, `flashpaste mcp`, `flashpaste dispatch`) plus an MCP server giving the agent real eyes (screenshots returned as PNG content) and hands (clipboard read/write + cross-pane paste). |
Using flashpaste
flashpaste is a thin Rust + bash stack that makes image paste actually work on GNOME / mutter / Wayland (where the bare wl-clipboard pipeline is broken for surfaceless clients), and exposes the same primitives to AI agents over MCP. It has three personas:
- A CLI, for humans and shell scripts.
- A daemon (
flashpasted) that owns the clipboard and fans out paste events in <15 ms.
- An MCP server (
flashpaste-mcp) that hands agents tools to see the screen, read/write the clipboard, and paste between panes.
When the user says "paste this screenshot into my terminal", "show this to Claude", "send this output to my other Codex pane", or "what does my screen look like?" — that's flashpaste territory.
The CLI (humans + scripts)
Since v1.19 the primary form is the unified flashpaste <subcmd> verb. The legacy binaries (flashpaste-shoot, flashpaste-trigger, flashpaste-dispatch, flashpaste-mcp, flashpaste-doctor, flashpasted) are still on $PATH and unchanged — flashpaste just dispatches to them with inherited stdio.
| Command | Wraps | Purpose |
|---|
flashpaste doctor [--json] | flashpaste-doctor | 13 parallel environment checks (Wayland session, mutter, kitty, tmux, wl-clipboard, xclip, ydotool socket, screenshots dir, daemon socket, etc.). Run this first when anything misbehaves. |
flashpaste shoot [--interactive] [--output <PATH>] [--print-path] [--annotate] | flashpaste-shoot | Captures the screen via XDG portal. Default: full-screen, saved to ~/Pictures/Screenshots/. --interactive opens the portal's area picker. --print-path writes the saved path to stdout. |
flashpaste paste <PANE> | flashpaste-trigger <PANE> | Trigger a paste of the current clipboard into <PANE> (e.g. %4). Goes through the daemon (~5 ms); falls back to the bash dispatch if the daemon is down. |
flashpaste dispatch <PANE> | flashpaste-dispatch <PANE> | Same as the bash tmux-paste-dispatch.sh but in Rust (~40 ms). Used as a fallback when the daemon is intentionally disabled. |
flashpaste daemon {start|stop|restart|status|logs} | systemctl --user / journalctl --user against flashpasted.service | Lifecycle for the Tier 3 daemon. |
flashpaste mcp | flashpaste-mcp | The MCP server. Spawned by Claude Code / Cursor / etc. via the MCP config. Not meant for humans to call directly. |
flashpaste version | — | Print the build version. |
Common CLI recipes
flashpaste shoot --interactive --print-path
flashpaste-shoot --interactive --annotate --print-path
flashpaste shoot && sleep 0.2 && flashpaste paste '%4'
flashpaste shoot --output ~/tmp/bug.png --print-path
flashpaste doctor
flashpaste daemon logs
Listing tmux pane ids
flashpaste-trigger and paste_to_pane need a pane id like %4. To enumerate panes (so the agent can pick the right target):
tmux list-panes -aF '#{pane_id} #{session_name}:#{window_index}.#{pane_index} #{pane_current_command}'
The current pane: tmux display-message -p '#{pane_id}'.
The MCP server
Once flashpaste-mcp is registered in ~/.config/claude-code/mcp.json (see README), the following tools become callable:
take_screenshot(interactive?: bool)
Captures the screen and returns the PNG as image content the model can see directly (not just a path). Use whenever:
- The user asks "what's on my screen?", "look at this", "see what I'm doing".
- You're debugging a visual UI bug and need ground truth.
- The user described something visually and you need to verify your understanding.
{"name": "take_screenshot", "arguments": {"interactive": true}}
read_clipboard()
Returns the current clipboard text. Use when the user copied something and wants you to inspect it without re-pasting.
copy_text(text: string)
Places text on the user's clipboard so they can paste it elsewhere (browser, editor, etc.).
paste_to_pane(pane_id: string)
Trigger flashpaste to paste the clipboard into a specific tmux pane. This is the cross-agent hand-off primitive — if there are two Claude Code panes (or one Claude Code + one Codex), and the user wants you to drop output into the other, copy to clipboard first then call this:
{"name": "copy_text", "arguments": {"text": "Here's the function you asked for: ..."}}
{"name": "paste_to_pane", "arguments": {"pane_id": "%5"}}
Daemon route: sub-15 ms round-trip. Falls back to the bash dispatch if the daemon is down (still <200 ms).
When NOT to use flashpaste tools
- For reading files: use the built-in
Read tool, not read_clipboard — the clipboard is volatile and not a substitute for filesystem access.
- For writing text into the current pane: don't
paste_to_pane your own pane — just emit the text. Cross-pane paste is for handing off to another agent or terminal.
- For screenshots of code: prefer reading the source file. Use
take_screenshot only when the visual surface is what matters (UI bugs, error dialogs, design mocks).
Troubleshooting playbook
If image paste / screenshot tools aren't working, run these in order:
flashpaste doctor
flashpaste daemon status
ls -la $XDG_RUNTIME_DIR/flashpaste.sock
flashpaste daemon logs
pgrep -cx wl-copy
Most failures correspond to a flashpaste doctor row going red. Read its output before guessing.
See also
- README: full architecture + install + troubleshooting matrix.
- ROADMAP.md: where the project is going (Rust daemon is Phase 2; MCP integration is Phase 3).
- AGENTS.md (in the repo root): canonical contribution guide.
