Let Codex, Claude Code, and Cursor Compress Images with PiPic

zimmer — Thu, 13 Aug 2026 09:00:53 +0000

Your coding agent can run a build and edit the code that ships it. Image
compression often ends with a tool installation, a throwaway script and output the
agent cannot interpret reliably.

PiPic uses a two-part setup instead:

@pipic/cli performs the image compression.
PiPic Skill teaches the agent when and how to call that CLI.

PiPic is not an AI compression model. The agent operates the tool; the hosted PiPic
service compresses PNG, JPEG, WebP and AVIF files.

Install the CLI and Skill

Run the setup yourself once:

npm i -g @pipic/cli
pipic login

npx skills add PiPic-cc/pipic-cli -g \
  -a claude-code \
  -a codex \
  -a cursor \
  -y

The short form below asks which supported agents should receive the Skill:

npx skills add PiPic-cc/pipic-cli -g

The Skill source is public in the
PiPic CLI repository.

Ask in plain English

After setup, the task does not need a product name or flags:

Compress the images in ./assets in place.

The Skill matches image compression, shrinking and optimisation requests. It checks
that pipic exists and that the machine is signed in. “In place” gives it an
explicit destination, so the agent runs:

pipic ./assets --replace --json

To preserve the originals, ask for a separate output directory. The agent then uses:

pipic ./assets -o ./compressed --json

--replace and -o are mutually exclusive, and one is required. PiPic exits with
a usage error before uploading anything when the destination is missing.

Give the agent a result it can parse

With --json, stdout contains one NDJSON object per file:

{"file":"assets/hero.png","status":"ok","before":2316198,"after":723577,"saved":1592621}

Those byte counts come from a published PiPic Agent CLI 1.0.6 benchmark run over a
licensed PNG. They demonstrate the output shape; results vary by image.

Every row has file, status, before, after and saved. Skipped and failed rows
also include error. status is always one of:

ok: a smaller result was written.
skipped: the original stayed in place, often because the result was larger.
error: the file failed and may need attention.

The Skill explicitly teaches the agent that skipped is not a failure. Without that
rule, an agent can report an already-optimised image as broken.

Branch on exit codes

Code	Meaning	What the agent does
0	Everything succeeded	Summarises the rows and stops
1	Some files failed	Re-runs only paths with `status: "error"`
2	Usage error	Fixes the command instead of repeating it
3	Sign-in required	Stops and asks the user to sign in
4	Monthly allowance exhausted	Stops; a retry cannot help

Retry scope matters because every accepted file uses monthly allowance. If two files
fail in a 100-file directory, re-running the entire directory uploads the other 98
again. The Skill tells the agent to retry only the two failed paths.

It also tells the agent never to run pipic login. That command opens a browser or
waits for device-code approval. A coding agent cannot provide the human approval and
should stop instead of waiting for a timeout.

Know what each part does

PiPic Skill is an instruction file. It does not contain an encoder or transport
image bytes. The CLI resolves files, calls the hosted compression service, writes
smaller output atomically and returns structured results.

The remote MCP endpoint is separate and read-only. It helps agents discover the CLI
and HTTP API; images do not move through JSON-RPC.

CLI images leave the machine for processing and are deleted from the server as soon
as compression completes. Teams that require local-only processing should choose a
local encoder. PiPic CLI and API offer 100 images per month on Free and 5,000 on Pro;
the browser compressor remains free, unlimited and account-free.