Tephra

Tephra is a private, in-memory clipboard for AI agents, living entirely inside a server process. An agent copies byte ranges from files into named slots and pastes those exact bytes anywhere in any open file.

• No OS Clipboard Integration: The operating system clipboard is never touched.
• Ephemeral Storage: Nothing is written to disk; all stored snippets vanish when the session ends.
• Protocol: Connects as an MCP server over stdio transport. Any MCP-compatible client can use it.

The Problems Tephra Solves

Tephra solves two problems that arise when agents edit files by line number:

1. Line-Number Drift

Every cut or paste shifts the line numbering of everything below the edit. When multiple agents work on one file, or when a single agent makes several edits in sequence, coordinates go stale and edits land in the wrong place.

The Fix: Tephra accepts every range in a single call addressed against the file as the agent last read it, applies every operation from the bottom of the file upward, and recalculates every line-number shift as the file changes. One read, one call, all arithmetic handled automatically.

2. Operating System Clipboard Leakage

An agent that reads the OS clipboard can see passwords and tokens the human copied. An agent that writes the OS clipboard can overwrite what the human is about to paste.

The Fix: Tephra keeps every slot inside the server process, so clipboard contents never cross the OS boundary.

Tools Reference

• copy — Copy one or more byte ranges from a file into clipboard slots. Each range is specified as {start_line, end_line, whole_lines?, start_char?, end_char?, slot?, expect}. Both ends are inclusive and 1-indexed. Newlines within a range travel with the copied text.
• cut — Same shape as copy, and also removes the ranges from the source file. Ranges in a single cut call must not overlap. Whole-line cuts remove the trailing newline as well, leaving no blank line behind.
• paste — Insert clipboard slots into a file at one or more targets specified as {line, char?, slot?, expect}. The paste lands before the character at (line, char). char defaults to 1; set char to line_length + 1 to append to the end of a line. Passing end_line or whole_lines: true replaces a range with the slot contents instead of inserting, and the result reports exactly what was removed.
• move — Cut and paste in one atomic call: move(file, ranges, to: {file?, line, char?, expect}). Source ranges and destination use the file's current coordinates. The server handles all shift arithmetic, so moving a block of lines to an earlier position works correctly even though the cut shifts the destination's line number. Cross-file moves are allowed.
• peek — List the slots holding text, or show one slot's size and a preview of its content.

Robustness & Drift Prevention

Three core mechanisms keep edits correct as line numbers shift:

Bottom-Up Batches

Every range and target in a single call is addressed against the file as the agent last read it and applied from the bottom of the file upward. No range invalidates another's coordinates.

Required expect Anchors

Every position named in copy, cut, paste, or move must carry a short snippet of adjacent text (up to 200 characters) — either the text starting at that position or the text ending at it (natural for appends).

• On mismatch, nothing is modified.
• The error reports what text actually sits at that position and where the agent's expected text now lives, making recovery a single round-trip.
• Stale coordinates fail closed as a loud no-op rather than open as a silent wrong edit.
• Catches every source of drift, including edits made outside Tephra or hallucinated tokens.
• Exception: Pasting into an empty file, where no text exists to verify.

Shift Reports

Every cut and paste result states how line numbers moved and reports the file's new addressable line count. Positions noted earlier can be recomputed instead of going silently stale.

Addressing & Coordinates

Addressing favors line-level operations because models read line numbers well and count characters with difficulty:

• Whole Lines: Uses {start_line, end_line, whole_lines: true}, and the trailing newline travels with them.
• Character Positions: Optional refinements. Omitting end_char means end-of-line; omitting start_char (or char on paste) means column 1.
• Indexing: When character positions are given, they are 1-indexed and inclusive on both ends.
• EOF Appends: A file ending in a newline has an addressable empty final line. Appending at end-of-file is a paste at (lastLine, 1).
• Self-Correction: Out-of-range positions return the line's real length and a preview, allowing the agent to self-correct in one step.

Advanced Mechanics

Named Slots

Available on every range and target through an optional slot parameter (defaults to "default"). Named slots let an agent gather many snippets in one pass, each into a distinct slot, then paste those snippets in any order, any number of times. Multi-range calls must assign a distinct slot name to each range.

Move Destinations & Collision Semantics

• A destination falling inside a moved range is rejected and nothing is modified.
• A destination between moved ranges follows gather-at-point semantics: unmoved text keeps relative order, and the concatenated payload of all moved ranges lands at the destination.
• A destination at a moved range's own boundary produces no change.

expect Behavior in Replace Mode

The expect field anchors at the start of the addressed range. It functions as a position check, not a content-of-range check. The server verifies the text adjacent to the anchor and may extend verification past the replaced range's end. Passing the stale block's first few characters is sufficient; reproducing the whole span being overwritten is unnecessary.

Requirements

• Runtime: Node ≥ 18
• Dependencies: Zero native dependencies, zero operating system clipboard backends.
• Process: The buffer lives entirely in the server process.

Part of Volcanic.