llms.txt

# FlashPaste

> FlashPaste is the missing glue that makes image-paste *just work* into terminal AI agents (Claude Code, Codex CLI, Aider) on GNOME Wayland. It works around mutter's surfaceless-client clipboard refusal, kitty's `map ctrl+v` interception, and tmux's `bind -n C-v` recursion via three progressive performance tiers: bash hot path (~127 ms), Rust one-shot dispatch (<40 ms), and a persistent daemon (<15 ms). The same MCP surface now includes an agent overlay for screen annotation: `highlight_region`, `point_at`, and `clear_annotations` let agents draw temporary highlights and pointers over visible Linux UI. Tier 1 is always on; Tiers 2 and 3 fall back transparently. MIT-licensed. Ships as a Debian `.deb`, a curl|bash bootstrap, or a built-from-source Rust workspace.

The canonical stack FlashPaste targets is **GNOME Wayland + kitty + tmux + a terminal LLM agent**. If you are running Sway, Hyprland, or another wlroots compositor, `wl-clip-persist` is the right answer and you do not need FlashPaste.

## Docs

- [README](README.md): Project overview, install commands, configuration snippets, the three-tier latency story, and the contract surface
- [Install guide](docs/install.md): Debian/Ubuntu `.deb`, curl|bash bootstrap, build-from-source, per-distro notes, and post-install activation
- [Architecture](docs/architecture.md): Deep dive on Tier 1 (bash dispatcher), Tier 2 (Rust one-shot), Tier 3 (persistent daemon + 1-byte trigger), and the kitty IPC + daemon socket protocols
- [Overlay quickstart](docs/overlay-quickstart.md): Agent-driven screen annotation setup, GNOME caveat, and demo recording recipe for `highlight_region`, `point_at`, and `clear_annotations`
- [Overlay protocol](docs/overlay-protocol.md): JSON-over-Unix-socket protocol for temporary screen highlights, pointer arrows, labels, TTLs, and overlay cleanup
- [FAQ](docs/faq.md): Twenty-plus questions and answers — image-paste failures, mutter wedge behaviour, daemon vs one-shot trade-offs, MCP, agent integration
- [Troubleshooting](docs/troubleshooting.md): Symptom → cause → fix tables, log locations, the diagnostic flowchart for "image paste isn't working"
- [Comparison vs alternatives](docs/comparison.md): FlashPaste vs `wl-clip-persist`, `cliphist`, OSC 52, manual `wl-paste | kitty @ send-text`, browser-based paste flows
- [Use cases](docs/use-cases.md): Specific scenarios — pasting screenshots into Claude Code on Ubuntu 24.04, Codex CLI on Fedora, Aider on Debian
- [Glossary](docs/glossary.md): Definitions of every domain term used in the codebase — mutter, surfaceless client, wlroots, wl-data-control, OSC 52, recursion guard, app_id

## Agents

- [AGENTS.md](AGENTS.md): Authoritative rules for AI agents and human contributors editing the repo — the non-negotiable release workflow, the four hard-won facts the code must preserve, the parallel-agent rules of engagement, version-number policy
- [ROADMAP.md](ROADMAP.md): Phase 1–4 plan covering shell cleanup, Rust performance, features, and distribution

## MCP tools

- `take_screenshot`: Capture the user's screen through `xdg-desktop-portal` and return PNG bytes + MIME
- `read_clipboard`: Read the current Wayland clipboard selection as text or image with MIME
- `copy_text`: Place text on the clipboard through the stable daemon owner
- `paste_to_pane`: Send a paste to a specific kitty/tmux pane by id, even when unfocused
- `highlight_region`: Draw a temporary rectangle or circle highlight on the user's visible screen
- `point_at`: Draw a temporary screen pointer arrow toward a button, panel, app region, or other visible UI target
- `clear_annotations`: Remove active overlay highlights, pointers, and labels

## Keywords

screen annotation, agent overlay, mcp screen pointer, linux ai overlay, Wayland clipboard, GNOME overlay, terminal AI, MCP server, Model Context Protocol

## Optional

- [LICENSE](LICENSE): MIT license text
- [CITATION.cff](CITATION.cff): Citation File Format metadata for academic / blog references
- [examples/](examples/): Verbatim tmux + kitty config snippets to append to your dotfiles
- [systemd/](systemd/): User unit files — `clipboard-janitor.service`, `flashpaste-screenshot-watcher.{path,service}`, `flashpasted.service`
- [packaging/](packaging/): Debian `.deb` build tooling (`build-deb.sh`, control templates)