imag

Fast, zero-config CLI to batch-convert images to WebP and AVIF — built in Go.
Built for web projects, CI, and AI coding agents (skills-ready).

imag is a lightweight command-line image optimizer for the web: convert PNG / JPG / GIF / … → WebP or AVIF, resize safely, run presets (seo, ecommerce, thumbnail), and emit a machine-readable JSON report so scripts and AI agents can update assets without burning vision tokens.

Keywords: image conversion CLI, WebP converter, AVIF converter, batch image optimize, SEO images, e-commerce product images, AI coding agent tool, Claude Code skill, Grok skill, CI image pipeline, no cloud, Go CLI.

$ imag -format auto -input ./assets -preset ecommerce -json -quiet

{
  "ok": true,
  "converted": 42,
  "bytes_in_total": 12000000,
  "bytes_out_total": 4100000,
  "bytes_saved_total": 7900000,
  "items": [ { "source": "...", "target": "...", "status": "converted" } ]
}

Current version line: see VERSION (e.g. v0.2.0-beta).

Why imag?

Need	imag
Batch convert a folder tree	Yes, concurrent workers
Web formats (WebP / AVIF)	Yes
CI / scripts	Exit codes + `-json`
AI agents (Claude, Grok, Cursor…)	Skill package + CLI contract
GUI / SaaS / API key	No — local binary only

Features

Convert JPG, PNG, BMP, GIF, TIFF, JFIF, WEBP, AVIF (HEIC/HEIF partial) → WebP or AVIF
Recursive batch + multi-core workers
-format auto (graphics → WebP, photos → AVIF)
Proportional resize (-max-width / -max-height, no upscale)
Presets: seo, ecommerce, thumbnail
-dry-run, -verbose, -include / -exclude, -ignore-dirs, -overwrite
Byte report (human + JSON): in / out / saved
PATH helpers: -check-path, -install-path
Exit codes: 0 ok · 1 fatal · 2 partial failure
Agent skill under skills/imag/ with install scripts

Install CLI

A) GitHub Release (recommended)

Download the binary for your OS from Releases
- Windows: imag-<tag>-windows-amd64.exe
- Linux: imag-<tag>-linux-amd64
- macOS Intel / Apple Silicon: darwin-amd64 / darwin-arm64
Rename to imag / imag.exe and put it on your PATH, or run:

imag -install-path          # asks [y/N]
imag -install-path -yes     # scripts / explicit approval only

Verify:

imag -version
imag -check-path

B) Go install

go install github.com/BrendownFerreira/imag/cmd/imag@latest
# ensure $(go env GOPATH)/bin is on PATH
imag -version

C) Helper scripts (from a clone)

git clone https://github.com/BrendownFerreira/imag.git
cd imag

# Unix
./skills/imag/scripts/install-cli.sh

# Windows PowerShell
.\skills\imag\scripts\install-cli.ps1

D) Build from source

git clone https://github.com/BrendownFerreira/imag.git
cd imag
go build -ldflags "-X main.version=$(tr -d '[:space:]' < VERSION)" -o imag ./cmd/imag
# Windows: go build -ldflags "-X main.version=v0.2.0-beta" -o imag.exe ./cmd/imag
imag -install-path   # optional

Install agent skill (Claude, Grok, & others)

The skill teaches agents when and how to run imag (install CLI first).

Canonical package: skills/imag/ · overview: skills/README.md

git clone https://github.com/BrendownFerreira/imag.git
cd imag

# Install skill into user skill dirs (Claude / Grok / generic)
./skills/imag/scripts/install-skill.sh --scope user      # Unix
.\skills\imag\scripts\install-skill.ps1 -Scope User    # Windows

# Optional: this project only
./skills/imag/scripts/install-skill.sh --scope project

Host	Typical path after install
Claude Code	`~/.claude/skills/imag/` or `.claude/skills/imag/`
Grok CLI	`~/.grok/skills/imag/` or `.grok/skills/imag/`
Generic	`~/.agents/skills/imag/` or `.agents/skills/imag/`

Then agents can use /imag (or auto-invoke from description keywords: optimize images, webp, avif, compress assets…).

Version alignment: skill frontmatter metadata.imag_cli_min and root VERSION must stay in sync when you cut a release. Agents should upgrade the CLI if -version is older than the skill minimum.

Quick start

# WebP everything here
imag -to webp

# Auto format for a folder
imag -format auto -input ./images

# E-commerce preset
imag -format auto -input ./products -preset ecommerce

# Preview only
imag -format auto -input ./assets -dry-run -verbose

# Agent / CI style
imag -format auto -input ./assets -preset seo -json -quiet \
  -ignore-dirs node_modules,.git,dist,build,.next

Commands & flags

Flag	Description	Default
`-to`	Target: `avif` or `webp`	interactive (TTY) / `auto` (non-TTY)
`-format`	`avif`, `webp`, or `auto`	—
`-input`	Source file or directory	current directory
`-output`	Destination file or directory	beside source
`-quality`	`1`–`100`	format default
`-preset`	`seo` \| `ecommerce` \| `thumbnail`	—
`-max-width` / `-max-height`	Cap size (keep aspect, no upscale)	—
`-overwrite`	Replace existing outputs	`false`
`-dry-run`	Simulate	`false`
`-verbose`	Per-file log (stderr if `-json`)	`false`
`-quiet`	Hide banner	`false`
`-json`	JSON manifest on stdout	`false`
`-version`	Print version	—
`-check-path`	PATH status	—
`-install-path`	Register on PATH (authorization)	—
`-yes`	Confirm prompts	`false`
`-include` / `-exclude`	Extension filters	—
`-ignore-dirs`	Skip dir basenames	—

Both -flag and --flag work.

Exit codes

Code	Meaning
`0`	Success
`1`	Fatal error
`2`	Partial failure (some files failed)

Format auto

Source	Target
`png`, `gif`, `bmp`	`webp`
`jpg`, `jpeg`, `jfif`, `tif`, `tiff`, `heic`, `heif`	`avif`
`webp`, `avif`	keep / skip

HEIC/HEIF decode may still fail (image: unknown format). Animated GIF → first frame only.

JSON report

imag -format auto -input ./assets -preset seo -json -quiet

Useful fields: ok, converted, failed, bytes_*_total, items[] with source, target, status, bytes_in / bytes_out / bytes_saved.

Full contract: skills/imag/references/cli-contract.md.

Human mode also prints size totals when measured (Bytes entrada / saida / economizados).

Presets

Preset	WebP quality	AVIF quality	Max size
`seo`	82	60	1920px wide
`ecommerce`	80	58	1600×1600
`thumbnail`	72	50	600×600

Manual flags always override presets.

For AI agents

Goal	Do this
Discover how to operate imag	Install `skills/imag` or read this README + cli-contract
Install CLI from the repo	`skills/imag/references/install.md` or install scripts
Save tokens	Use `-json`; do not load image binaries into vision for size checks
Safe on monorepos	Always `-ignore-dirs node_modules,.git,dist,build,.next`
Failures	Exit `2` / `"ok": false` = partial failure

Canonical agent command:

imag -format auto -input <path> -preset seo \
  -ignore-dirs node_modules,.git,dist,build,.next \
  -json -quiet

GitHub-facing git text (commits, tags, release notes) is English by default.

MCP is optional later; the supported path today is CLI + skill.

Documentation

Doc	Purpose
docs/README.md	Doc map
docs/prd/PRODUCT.md	PRD
docs/sdd/ARCHITECTURE.md	SDD
docs/backlog/READY.md	Backlog ready
docs/backlog/DONE.md	Backlog done
docs/RELEASE.md	How to publish releases
skills/README.md	Skill install & version sync
VERSION	Current version string

Development

go get -u ./...
go mod tidy
go test ./...
go build -ldflags "-X main.version=v0.2.0-beta" -o imag.exe ./cmd/imag

Releases

Pushing main alone does not publish a Release.
Push a tag v* (e.g. v0.2.0-beta) or use Actions → Release workflow.
Tags with -beta are prereleases (no green Latest badge until a non-prerelease tag).
Details: docs/RELEASE.md.

When releasing: bump VERSION + skill metadata in skills/imag/SKILL.md together.

Roadmap

docs/backlog/READY.md · DONE.md
Next ideas: info/list, only-if-smaller, honest HEIC, package managers

Contributing

Issues and PRs welcome. Open an issue before large changes. Prefer English for commit messages and PR titles.

License

Source-available. Free for personal and non-commercial use.
Commercial use requires permission from the author.

See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
cmd/imag		cmd/imag
docs		docs
skills		skills
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
go.mod		go.mod
go.sum		go.sum

Navigation Menu

Repository files navigation

imag

Table of contents

Why imag?

Features

Install CLI

A) GitHub Release (recommended)

B) Go install

C) Helper scripts (from a clone)

D) Build from source

Install agent skill (Claude, Grok, & others)

Quick start

Commands & flags

Exit codes

Format auto

JSON report

Presets

For AI agents

Documentation

Development

Releases

Roadmap

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

imag

Table of contents

Why imag?

Features

Install CLI

A) GitHub Release (recommended)

B) Go install

C) Helper scripts (from a clone)

D) Build from source

Install agent skill (Claude, Grok, & others)

Quick start

Commands & flags

Exit codes

Format auto

JSON report

Presets

For AI agents

Documentation

Development

Releases

Roadmap

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages