Px Pipe

CI License: MIT

Turn a large paste, file, or clipboard into a dense PNG image that Claude reads by vision (~3× cheaper than text tokens) — with a verbatim appendix of any byte-exact tokens so nothing lossy has to be trusted from pixels.

Type pipethis: <big blob> in Claude Code and it renders → stores → loads the image in one step, zero interaction. Built on pxpipe (the pxpipe-proxy npm package — no fork, just a pinned dependency).

Ships three ways to use the same engine: an MCP server (primary), a CLI (render.mjs, the fallback), and a Claude Code skill (the pipethis: trigger).

---

Quick start (one clone)

git clone https://github.com/dbbuilder-org/pipethis.git
cd pipethis

# macOS / Linux
./install.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\install.ps1

Then restart Claude Code and type:

pipethis: <paste a large log / doc / transcript here>

The installer: installs deps (pnpm or npm), registers the MCP server with Claude Code at user scope, and installs the pipethis skill. It's re-runnable.

Prerequisites: Node.js ≥ 18 and the claude CLI. pnpm is used if present, otherwise npm. Linux clipboard needs one of wl-paste / xclip / xsel.

Manual install (what the installer does)

Prefer to wire it up yourself:

cd pipethis
pnpm install                                            # or: npm install
claude mcp add --scope user pipethis -- node "$PWD/server.mjs"
mkdir -p ~/.claude/skills/pipethis
sed "s#__PIPETHIS_DIR__#$PWD#g" skill/pipethis/SKILL.md > ~/.claude/skills/pipethis/SKILL.md
# then restart Claude Code

---

What it does

big content (paste / file / clipboard)
  → pxpipe renderTextToImages()            dense PNG page(s)
  → returned as image block(s)             model reads by vision
  + byte-exact tokens appended verbatim    URLs, IDs, env keys, hashes

Text priced at ~1 char/token becomes an image priced by pixels (~3.1 chars/image token), so a big blob typically drops 75–90% of its input tokens. Recent-turn content stays text; only the pasted blob is imaged.

Example

You type:

pipethis: # Billboard SSO setup
Redirect URI (exact): https://billboard-api-8692.onrender.com/api/auth/sso/callback
Set Entra__ClientId / Entra__ClientSecret on the API. Tenant 11111111-2222-3333-4444-555555555555.
… (a few thousand more chars) …

Claude renders it in one step and replies from the image, e.g.:

Rendered 2987 chars to 1 image page(s): 739 text tokens -> 184 image tokens (~75% saved).
Stored at: ~/.pxpipe/pastes/1783381685645/page-1.png
Exact values (verbatim — trust these over the image):
  code_block.1: https://billboard-api-8692.onrender.com/api/auth/sso/callback
  env.1: Entra__ClientId
  env.2: Entra__ClientSecret
  guid.1: 11111111-2222-3333-4444-555555555555

The gist comes from the cheap image; the must-be-exact strings come through the appendix verbatim — so a redirect URI or ID is never trusted from pixels.

MCP tools

Tool	Args	Use
render_text_as_image	text, gate*	Text (what pipethis: calls).
paste_clipboard_as_image	gate*	Whatever is on the clipboard.
render_file_as_image	path, gate*	A file's contents.

*gate = minChars? (default 2000), exact? (true = keep as text), extractExact? (default true = append the verbatim byte-exact list). Each result is a savings summary + the stored path + image block(s) + the Exact-values appendix.

CLI (fallback)

node render.mjs --file /abs/blob.log        # or --stdin, or clipboard (default)
node render.mjs --stdin --min-chars 1       # force-image piped input
node render.mjs --file x --exact            # refuse to image, keep text

Prints JSON: pages[] (PNG paths to Read), savedPct, warnings, exactValues.

Safety (mixed content)

• Size gate — content under minChars isn't imaged (imaging tiny blobs loses money).
• exact: true — skips imaging entirely; keep content as text.
• Fidelity warning — a heuristic flags likely code/exact data even when it renders.
• Exact-values appendix (extractExact, default on) — best of both: the image carries the gist cheaply, and byte-exact tokens are appended below it as verbatim <type>.<n>: <value> text. Extracts code-block contents, env keys (Foo__Bar), URLs, GUIDs, emails, hashes, and inline-code spans — deduped, with fragments of an already-captured value suppressed.

Refusals return a plain-text block naming the reason (no_input, below_min_chars, exact_requested, render_error) — a decision, not an error.

Troubleshooting

• pipethis: does nothing / tools missing — restart Claude Code after installing; MCP tools load at session start. Check with claude mcp list (should show pipethis … ✔ Connected) or /mcp inside Claude Code.
• "claude CLI not found" — install Claude Code, then re-run the installer (or do the claude mcp add from Manual install).
• Clipboard tool returns nothing on Linux — install wl-clipboard, xclip, or xsel. On headless boxes, use render_file_as_image / --file instead.
• Everything gets refused as below_min_chars — the content is under 2000 chars; pass minChars: 1 (the pipethis: path already does).
• An exact value looks wrong in the image — that's expected; read it from the Exact values appendix, not the pixels. For fully verbatim content use exact: true to keep it as text.

Uninstall

./uninstall.sh            # macOS / Linux  (removes MCP registration + skill)

Windows: claude mcp remove --scope user pipethis and delete %USERPROFILE%\.claude\skills\pipethis.

Develop

node --test               # unit (lib) + CLI + stdio MCP integration

Everything shares one core (lib.mjs): renderBlob (gate + render + savings) and extractExactValues (the appendix). server.mjs is the MCP wrapper, render.mjs the CLI wrapper — no duplicated logic.