pi-pasteboard

Keeps large pastes out of model context. Segments typed text and pasted content at the TUI boundary, saves pastes as private local files, and gives the model file references instead of 100 KB paste blobs. Automatic, transparent, zero-config.

pi-pasteboard is a standalone Pi package that keeps very large interactive TUI submissions out of the model context. It offers two capture strategies that activate automatically:

• v2 segmented (active by default): Intercepts paste boundaries BEFORE marker expansion via a custom editor wrapper. Pastes are saved as individual private files; typed text stays inline. The model sees file references instead of huge paste blobs.
• v1 whole-input (fallback): Hooks the input event with a 32 KiB size threshold. The entire submission is saved as one content-addressed file. Used when the custom editor cannot install or paste internals are unreachable.

How it works (v2 segmented)

Pi's editor collapses large pastes (>10 lines or >1000 chars) into display markers like [paste #1 +123 lines]. Before submit these markers and the pastes Map coexist — afterwards markers are expanded and the Map is cleared, forever losing the typed/paste boundary.

pi-pasteboard installs a custom editor wrapper on session_start via ctx.ui.setEditorComponent() that monkey-patches submitValue(). The wrapper reads marker-bearing text and the runtime pastes Map BEFORE expansion, then:

1. Parses the marker text into ordered segments: typed → paste → typed → paste → typed.
2. Saves each paste to a 0600 file under /tmp/pi-pasteboard/submissions/<uuid>/paste-<N>.txt.
3. Writes a manifest.json with segment metadata (submission id, order, kind, file path, byte/line counts, timestamps, fallback reason if any).
4. Replaces each paste marker with [paste saved: <path>] so the model can read the file.
5. Lets the original submit flow continue — the model sees only short file references.

Example

User submits: Review this:\n + [paste 500 lines of code] + \nThanks! + [paste 200 lines of config]

The model receives:

Review this:
[paste saved: /tmp/pi-pasteboard/submissions/<uuid>/paste-1.txt]
Thanks!
[paste saved: /tmp/pi-pasteboard/submissions/<uuid>/paste-3.txt]

And can read each paste file individually via the read tool.

v1 whole-input fallback

The v1 input-event handler remains active as a safety net. When the custom editor cannot install (non-TUI modes, editor patching failure at runtime), or when pastes are absent, the existing 32 KiB threshold whole-input capture takes over:

• Writes the full submitted text to /tmp/pi-pasteboard/sha256-<hash>.txt.
• Replaces the prompt with: Large input captured at <path>. Read that file if needed; do not ask the user to paste it again.

The fallback is explicit: the manifest (v2) or the absence of a submission directory (v1) makes it clear which path was taken.

Install

From a checkout:

pi install /absolute/path/to/pi-pasteboard

For one run without installing:

pi -e /absolute/path/to/pi-pasteboard

The package manifest exposes ./src/index.ts as a Pi extension.

Safety notes

• /tmp/pi-pasteboard is created as mode 0700 and must be a current-user-owned directory, not a symlink.
• v1 paste files are mode 0600, content-addressed by SHA-256. Duplicate content reuses the same file.
• v2 paste files and manifests are mode 0600 under per-submission directories.
• Writes use same-directory temp files plus no-overwrite hard-link creation.
• Cleanup is best-effort: old sha256-*.txt files and expired submission directories are removed on session start.
• Default cleanup TTL is 7 days (PI_PASTEBOARD_TTL_MS may override). Default capture threshold is 32 KiB (PI_PASTEBOARD_MIN_BYTES may override).
• The pasteboard root directory is /tmp/pi-pasteboard by default. Override via PI_PASTEBOARD_ROOT env var.

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | PI_PASTEBOARD_ROOT | /tmp/pi-pasteboard | Storage root directory | | PI_PASTEBOARD_MIN_BYTES | 32768 | Minimum byte threshold for v1 whole-input capture | | PI_PASTEBOARD_TTL_MS | 604800000 (7 days) | Retention period for paste files and submission dirs | | PI_PASTEBOARD_DEBUG | unset | When 1, emits debug-level logs to stderr about mode selection, fallback decisions, and I/O operations |

With PI_PASTEBOARD_DEBUG=1, the extension logs whether v2 segmented capture is active, why a fallback occurred, and per-capture metadata (byte counts, file paths). Without it, only a transient TUI notification marks mode installation — no ongoing noise.

Limitations

Paste marker misidentification

If a user types literal [paste #N ...] text AND a matching paste ID exists in the Map (vanishingly rare — pastes are cleared every submit), the typed text is misidentified as a paste marker. The marker regex requires [paste # followed by a digit and optional +N lines or N chars suffix, which is unlikely in natural typing.

Small pastes

Small pastes (<10 lines, <1000 chars): Pi never creates markers for small pastes — they stay inline in the typed text. These are invisible to segmentation and remain in the prompt.

Synchronous I/O latency

Paste-segment files and the manifest are written synchronously inside the editor's submitValue() — the same call-path that runs the terminal render loop. Each submission writes N paste files + one manifest. On a local SSD with typical paste sizes (<1 MB each), this adds ~1–2 ms per file; a 5-paste submission might add <10 ms total, which is imperceptible. On a slow or network filesystem the per-file latency could reach tens of milliseconds.

To bound the worst case, the segmenter caps submissions at 50 segments (files). Exceeding the cap causes the patcher to fall back to v1 whole-input capture (one file). This is a hard guardrail — the submission is NOT silently corrupted; the original markers expand normally and the v1 input-event handler captures the expanded text.

Runtime field fragility

The pastes Map, pasteCounter, and state object are declared private in TypeScript but are regular JS fields at runtime. If Pi upstream changes these to ECMAScript #private fields, this.getText() (public API) still works but this.pastes / this.state.lines become unreachable. In that scenario the patcher falls back to v1 whole-input capture, and the transient notification (or debug log at PI_PASTEBOARD_DEBUG=1) documents the fallback reason.

Public API preference

The patcher reads marker text via this.getText() (the public, documented method) rather than this.state.lines.join("\n"). For writing transformed text back, it mutates state.lines directly rather than calling this.setText(). The public setText() exists on the Editor class but triggers onChange and autocomplete side effects during the critical submit-interception window. If a future Pi version makes setText() side-effect-free for this use case, the mutation can be switched to the public API.

Post-submit reconstruction impossible

Once markers are expanded and the pastes Map is cleared, there is no way to recover typed/paste boundaries. The editor wrapper is the sole interception window.

Compatibility with other custom editors

The wrapper composes with prior editor factories via ctx.ui.getEditorComponent(). If another extension installed a custom editor (e.g., vim mode), this wrapper delegates to it and then patches the result.

Factory-replacement fragility: If a third extension calls ctx.ui.setEditorComponent() AFTER pi-pasteboard installs its wrapper, the segmented capture is silently replaced. There is no hook to detect being swapped out. The v1 input-event fallback remains active regardless, so the worst outcome is falling back to whole-input mode mid-session. This is a Pi API limitation — extensions cannot "stack" editor factories.

Pi version requirement

v2 segmented capture requires @earendil-works/pi-coding-agent exporting the CustomEditor class (available since v0.15.0+). The import is dynamic — on older Pi versions the extension loads without crashing, emits a warning notification, and runs in v1 whole-input-only mode.

Conservative bypasses (v1 fallback)

The v1 input-event handler passes input through unchanged when it is:

• extension-sourced;
• not interactive TUI (rpc, json, and print modes are bypassed);
• below the size threshold;
• a slash command or bang command;
• likely to contain an @ file reference;
• carrying images or attachments;
• a steering message (streamingBehavior === "steer").

These bypasses do not apply to v2 segmented capture — if the editor wrapper is active, segmentation fires on every submit regardless of size/source (only large pastes have markers, so small submits are effectively no-ops).

Privacy

• Paste contents are written only to local temp files on your machine. Nothing is sent to any external service.
• Files are mode 0600 (v2 submissions) or 0600 (v1) — readable only by the file owner.
• The submission root (/tmp/pi-pasteboard) is mode 0700 — no other user can list contents.
• Paste content is never logged or stored in Pi's session history. Only the [paste saved: <path>] reference appears in the prompt.
• The manifest JSON records metadata (byte counts, timestamps, segment order) but does not include the text of typed segments longer than a few characters.
• Enable PI_PASTEBOARD_DEBUG=1 only for troubleshooting — debug output includes file paths but still excludes paste content.

Cleanup

Both v1 paste files and v2 submission directories are removed automatically on session start:

• Files/directories older than the TTL (default 7 days) are deleted.
• A .cleanup.lock file prevents concurrent cleanup from multiple Pi processes (stale locks expire after 10 minutes).
• To force immediate cleanup without starting a session: delete files/directories manually under /tmp/pi-pasteboard/.
• The root directory itself is NOT removed — only its contents.

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | No [paste saved:] refs in prompt — just expanded text | Editor wrapper not installed or fell back. v1 whole-input may still fire for large inputs. | Run with PI_PASTEBOARD_DEBUG=1 and check stderr for fallback reason. | | "CustomEditor unavailable" notification | Pi version too old (<0.15.0) | Update Pi; v1 fallback remains active. | | Submission feels laggy | Sync I/O on slow filesystem; many segments | Check PI_PASTEBOARD_ROOT isn't on a network drive. Segment cap (50) prevents worst case. | | Paste files not cleaned up | Stale lock or permission issue | Check /tmp/pi-pasteboard/.cleanup.lock and /tmp/pi-pasteboard/submissions/.cleanup.lock. Delete stuck lock files manually. | | Segmented capture stopped working mid-session | Another extension replaced the editor factory | This is a known limitation (see Limitations above). v1 fallback takes over. Restart session to reinstall. |

Development

npm test          # run all tests
npm run typecheck # TypeScript compilation check
npm run lint      # alias for typecheck

File layout

/tmp/pi-pasteboard/
├── sha256-<hash>.txt          # v1 whole-input files
├── .cleanup.lock              # cleanup mutual-exclusion lock
└── submissions/
    └── <uuid>/
        ├── manifest.json      # segment metadata
        ├── paste-0.txt        # paste segment files (0600)
        ├── paste-1.txt
        └── ...