imgstat — giving AI context about your images

LLMs can't see your images. They also can't infer dimensions unless you explicitly tell them. That gap is what imgstat solves.

I needed a simple way for my AI tools to know what kind of images they were working with, without opening files, parsing metadata, or guessing. So I built a small CLI that does one thing well.

imgstat scans a directory and renames images to include their dimensions:

photo.jpg → photo-1920x1080.jpg

Once the size is in the filename, the context becomes obvious, to humans and to AI.

Why this exists

When you're working with AI-assisted coding, filenames are context. But image files usually hide the most important detail.

I wanted something that works recursively, doesn't reprocess files unnecessarily, requires zero configuration, and can run almost anywhere. So I kept it intentionally simple.

Features

• AI-ready context, with image dimensions embedded directly in filenames
• Idempotent, so it skips files that are already renamed
• Recursive, handling deep directory structures
• Minimal surface area, with no runtime and no dependency explosion

Installation and usage

npm install -g imgstat

imgstat ./images

# You can also download and process directly:
imgstat -u https://example.com/images

Why it's written in Bash

I wanted this to run in as many environments as possible. No framework, no build step, no ceremony. Bash gives you predictable behavior, easy portability, and zero runtime assumptions.

On Windows, this works via WSL (recommended), Git Bash, or any POSIX-compatible shell environment. If you can run shell scripts, you can run imgstat.

Closing

This isn't a big tool. It's a small piece of glue that removes friction, especially when working with AI. Sometimes the best developer experience improvement is just making the context obvious.

Repository: github.com/isaac0yen/imgstat
npm: npmjs.com/package/imgstat