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 is not an AI compression model. The agent operates the tool; the hosted PiPic
service compresses PNG, JPEG, WebP and AVIF files.
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
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 up anything when the destination is missing.
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.
| 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.
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.
Full contract: PiPic Agent CLI documentation