Agent Image

A single-binary image processing CLI for AI agents, published as @codebolt/agent-image. Operations are composable via pipes, making it easy for agents to chain transformations in a single shell command.

Why

AI agents can process images, but they need simple, predictable CLI tools to do it. Agent Image gives them:

• No Rust required for users — run it with npx or install it from npm
• Composable via pipes — chain operations with |, no temp files needed
• Deterministic args — every parameter is a named flag with sensible defaults
• stdin/stdout by default — pipes use PNG format, so agents don't need to manage intermediate files

Install

Run directly:

npx @codebolt/agent-image --help

Install globally:

npm install -g @codebolt/agent-image
agent-image --help

The npm package installs a small Node launcher plus the matching prebuilt Rust binary for your platform. The old imagecli command is kept as a compatibility alias when installed from npm.

Build from source

cargo build --release --bin agent-image
# binary: ./target/release/agent-image

Usage

# Single operation
agent-image -i input.png -o output.png blur --sigma 3

# Piped chain: grayscale then sharpen
agent-image -i input.png grayscale | agent-image unsharpen --sigma 3 --threshold 5 -o output.png

# Cinematic teal/orange color grade
agent-image -i input.png -o output.png color-grade --shadows-hue=200 --shadows-sat=50 --highlights-hue=30 --highlights-sat=40

# Vintage 70s look: faded curve + warm color + color grading + vignette
agent-image -i input.png curve --darks=35 --highlights=-20 \
  | agent-image color --temperature=30 --saturation=-15 \
  | agent-image color-grade --shadows-hue=30 --shadows-sat=30 --highlights-hue=45 --highlights-sat=20 \
  | agent-image vignette --amount -70 -o output.png

Commands

| Command | Description | |---------|-------------| | blur | Gaussian blur | | unsharpen | Unsharp mask (sharpen) | | grayscale | Convert to black and white | | resize | Resize longest side to target | | channel | Extract a single RGB channel | | curve | Tone curve via 5-point cubic spline | | color | Temperature, tint, vibrance, saturation | | color-grade | Split-tone shadows/midtones/highlights | | vignette | Lightroom-style vignette | | show-curve | Debug: render a tone curve plot |

Run agent-image <command> --help for detailed argument info.

Using with AI agents

Agent Image is built to be called by AI agents that need image processing capabilities. The CLI surface is intentionally simple: named flags, numeric values, and predictable behavior.

Claude Code Skills

This project includes ready-made Claude Code Skills in .claude/skills/:

• process-image — Claude automatically translates natural language requests ("make it warmer", "add a cinematic look") into agent-image commands, runs them, and verifies the result

To use them, open this project in Claude Code and ask it to process an image. The skills are picked up automatically.

Other agents

Any agent with shell access can use Agent Image. The key patterns:

# Input from file, output to file
agent-image -i input.jpg -o output.jpg <command> [args]

# Input from stdin, output to stdout (PNG format)
cat input.png | agent-image blur --sigma 2 | agent-image grayscale > output.png

# Chain operations with pipes
agent-image -i photo.jpg resize -s 1024 | agent-image color --temperature=20 -o result.jpg

Film Emulation

You can tap into Claude builting knownledge of film caracteristic and convert this easily into a processing pipeline.

https://github.com/user-attachments/assets/bc833bbb-569b-4736-91f6-ce398e29bb47

FAQ

Why use pipes instead of combining all ops in one command?

Pipes keep each step independent and composable. Agents (and humans) can mix and match freely without learning a monolithic DSL.

What format does stdin/stdout use?

PNG. Use -i and -o for other formats (JPEG, etc.).

How do I see all options for a command?

Run agent-image <command> --help (e.g. agent-image curve --help).

Why your code sucks?

It's a pet project vibe-coded using Claude. I'm not a Rust programmer, so I wouldn't call the style "elegant". The performance is also not optimized at all (yet).

License

MIT