TinySquish for the terminal and AI agents

Install

You need Node.js 20 or newer. Run it without installing, or install it once to use it offline:

npx -y tinysquish photo.jpg --max 100kb
npm install -g tinysquish

The package uses sharp (libvips) and takes about 50 MB on disk. Source code: GitHub, MIT license.

Command line

# one photo under an upload limit
tinysquish photo.jpg --max 100kb -f jpeg

# a folder of images for a website, as WebP, into another folder
tinysquish ./images -f webp -o ./images-web

# lossless PNG, thumbnails, machine-readable output
tinysquish logo.png -q 95
tinysquish ./photos --width 400 -f webp -o ./thumbs
tinysquish ./screenshots --json

Inputs are never modified. Results are written as name-compressed.ext next to each input, or into --out. Folders are scanned recursively. Run tinysquish --help for every option.

MCP server for AI agents

The MCP server gives assistants such as Claude, Cursor and other MCP clients two tools: compress_images (files or folders, with quality, format, max size and resize options) and image_info. It runs as a local stdio process and opens no network connections.

Claude Code:

claude mcp add tinysquish -- npx -y -p tinysquish tinysquish-mcp

Claude Desktop, Cursor and other clients (mcpServers in their JSON config):

{
  "mcpServers": {
    "tinysquish": {
      "command": "npx",
      "args": ["-y", "-p", "tinysquish", "tinysquish-mcp"]
    }
  }
}

To limit which folders the agent can read and write, add --allow once per folder, for example "args": ["-y", "-p", "tinysquish", "tinysquish-mcp", "--allow", "/home/me/Pictures"]. Files that link outside those folders are refused too.

Agent skill

The skill teaches an agent when to reach for TinySquish and how to read its results. For Claude Code, save it as ~/.claude/skills/tinysquish/SKILL.md:

mkdir -p ~/.claude/skills/tinysquish
curl -fsSL https://raw.githubusercontent.com/mnuradli1/tinysquish.com/main/skill/tinysquish/SKILL.md   -o ~/.claude/skills/tinysquish/SKILL.md

It is also included in the npm package under skill/tinysquish/.

Runs on your machine

• No upload, no API key, no account. Images are read and written on the computer that runs the tool.
• No server in the loop. Bots and pipelines can call it as often as they like; nothing is sent to tinysquish.com.
• Same rules as the web app. Quality, lossless PNG from 90%, max size and “never larger than the original” behave the same way. The encoders are libvips instead of the browser's, so sizes are similar but not byte-identical.

Frequently asked questions