Read clipboard text or images and copy text without constructing platform-specific shell commands.
Use in Pi
Ask Pi to use the clipboard for your task.
The clipboard tool supports direct calls and codemode.
Direct image reads return image blocks; codemode callers can display result.image with image().
Direct call example:
{ "action": "read", "format": "text" }
Codemode examples:
const result = await tools.clipboard({ action: "read" });
text(result.text);
await tools.clipboard({ action: "copy", text: "Exact text to copy" });
const result = await tools.clipboard({ action: "read", format: "image" });
if (result.image) image(result.image);
Availability
Text copying uses Pi's native clipboard helper and requires interactive TUI mode because Pi may emit terminal escape sequences.
Reads use the Pi host's clipboard; remote copies may instead reach the client terminal through OSC 52.
Copy completion does not verify a subsequent paste.
Windows, macOS and X11 reads use Pi's native backend; Wayland reads require wl-paste from wl-clipboard and never fall back to potentially stale X11 contents.
File-reference reads (format: "files") require native backend support, currently macOS; they never open files.
Images are returned as PNG blocks, not temporary files; copying images, files, HTML or arbitrary binary formats is not supported.
Limits and privacy
A null value means the requested content is absent; unavailable access, malformed images, and oversized content fail explicitly rather than returning partial data.
Read limits are 32 KiB text / 48 KiB escaped text JSON, 4 MiB image input and PNG output bounded to 33554432 pixels (16384 px per side), and 128 file references / 32 KiB JSON.
Native backend reads and copies time out after a few seconds instead of hanging.
Copied text is limited to 64 KiB UTF-8; terminal clipboard limits may be lower.
Clipboard access occurs only on explicit tool calls, never through background polling.
Read results and copy arguments can persist in session history, so clipboard contents may expose secrets to the agent and provider.
The clipboard renderer keeps its own collapsed rows compact; expansion reveals text or images.
Codemode can display nested copy arguments and any content its script prints, so a collapsed parent row is not a privacy boundary.
<img src="assets/banner.svg" alt="clipboard" height="70">
# <img src="assets/icon.svg" alt="" height="28"> clipboard
Read clipboard text or images and copy text without constructing platform-specific shell commands.

## Use in Pi
Ask Pi to use the clipboard for your task.
The `clipboard` tool supports direct calls and codemode.
Direct image reads return image blocks; codemode callers can display `result.image` with `image()`.
Direct call example:
```json
{ "action": "read", "format": "text" }
```
Codemode examples:
```javascript
const result = await tools.clipboard({ action: "read" });
text(result.text);
await tools.clipboard({ action: "copy", text: "Exact text to copy" });
```
```javascript
const result = await tools.clipboard({ action: "read", format: "image" });
if (result.image) image(result.image);
```
## Availability
Text copying uses Pi's native clipboard helper and requires interactive TUI mode because Pi may emit terminal escape sequences.
Reads use the Pi host's clipboard; remote copies may instead reach the client terminal through OSC 52.
Copy completion does not verify a subsequent paste.
Windows, macOS and X11 reads use Pi's native backend; Wayland reads require `wl-paste` from `wl-clipboard` and never fall back to potentially stale X11 contents.
File-reference reads (`format: "files"`) require native backend support, currently macOS; they never open files.
Images are returned as PNG blocks, not temporary files; copying images, files, HTML or arbitrary binary formats is not supported.
## Limits and privacy
A `null` value means the requested content is absent; unavailable access, malformed images, and oversized content fail explicitly rather than returning partial data.
Read limits are 32 KiB text / 48 KiB escaped text JSON, 4 MiB image input and PNG output bounded to 33554432 pixels (16384 px per side), and 128 file references / 32 KiB JSON.
Native backend reads and copies time out after a few seconds instead of hanging.
Copied text is limited to 64 KiB UTF-8; terminal clipboard limits may be lower.
Clipboard access occurs only on explicit tool calls, never through background polling.
Read results and copy arguments can persist in session history, so clipboard contents may expose secrets to the agent and provider.
The clipboard renderer keeps its own collapsed rows compact; expansion reveals text or images.
Codemode can display nested copy arguments and any content its script prints, so a collapsed parent row is not a privacy boundary.
[Installation](../../README.md#install)
<!-- config:start -->
<!-- config:end -->