imagic-agent

A standalone CLI AI agent for image processing using natural language. Powered by the Imagic MCP server, it lets you convert formats, resize to presets, and merge images — all locally — by describing what you want in plain English.

How It Works

Your prompt → AI provider (Claude / GPT-4o / Gemini) → Imagic MCP tools → result

The agent uses the Vercel AI SDK to connect an AI model to the Imagic MCP server over stdio. The model decides which tools to call and can chain multiple operations automatically.

Requirements

• Node.js 18+
• API key for at least one supported provider

Installation

# Run without installing
npx imagic-agent

# Or install globally
npm install -g imagic-agent

Usage

Interactive mode

ANTHROPIC_API_KEY=sk-ant-... imagic-agent

Imagic Agent v1.0.0  |  Provider: Anthropic (claude-sonnet-4-6)
Type your request or "exit" to quit.

You: convert /tmp/photo.png to webp
Agent: Done! Saved to /tmp/photo.webp (42 KB).

You: resize it to instagram-square
...

Type exit or quit, or press Ctrl+C to exit.

Single-shot mode

Pass your request as a CLI argument and the agent exits after completing it.

imagic-agent "convert /tmp/photo.png to webp"
imagic-agent "resize /tmp/logo.png to favicon"
imagic-agent "merge /tmp/a.png /tmp/b.png /tmp/c.png into /tmp/merged.png as a grid"

Providers

The agent auto-detects the provider from your environment variables. You can also override it explicitly.

| Provider | Env var | Default model | |-----------|------------------------------------------------------|---------------------| | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 | | OpenAI | OPENAI_API_KEY | gpt-4o | | Google | GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY | gemini-2.0-flash |

Auto-detection priority: --provider flag → ANTHROPIC_API_KEY → OPENAI_API_KEY → Google key → defaults to Anthropic.

Override provider or model

imagic-agent --provider=openai "convert /tmp/a.png to webp"
imagic-agent --provider=google --model=gemini-1.5-pro "resize /tmp/logo.png to 512x512"

Available Tools

The agent has access to five tools from the Imagic MCP server:

| Tool | What it does | |----------------------|-----------------------------------------------------------------------| | convert_image | Convert a single image to PNG, JPEG, WebP, GIF, or ICO | | resize_image | Resize a single image to custom dimensions or a named preset | | convert_and_resize | Convert and resize a single image in one operation | | merge_images | Merge 2+ images horizontally, vertically, or in a grid | | process_folder | Apply convert/resize/convert_and_resize to all images in a folder |

Folder processing

Pass a folder path and the agent will find every image file automatically, skip non-images, and report per-file results. Supported input formats: JPG, PNG, GIF, WebP, BMP, TIFF, AVIF, HEIC/HEIF.

Resize presets

instagram-square, instagram-portrait, instagram-landscape, twitter-post, twitter-header, full-hd, 4k, youtube-thumbnail, favicon

Examples

# Convert a single file
imagic-agent "convert /tmp/photo.jpg to webp at quality 85"

# Resize to a social media preset
imagic-agent "resize /tmp/banner.png to twitter-header"

# Custom dimensions
imagic-agent "resize /tmp/avatar.png to 256x256, no aspect ratio lock"

# Merge images side by side
imagic-agent "merge /tmp/before.png and /tmp/after.png horizontally into /tmp/compare.png"

# Convert every image in a folder to WebP
imagic-agent "convert all images in /tmp/photos to webp"

# Resize all images in a folder to instagram-square, save to a new folder
imagic-agent "resize all images in /tmp/photos to instagram-square and save to /tmp/resized"

# Convert + resize an entire folder in one go
imagic-agent "convert all images in /tmp/shots to jpeg at quality 80 and resize to 1920x1080"

Tips

• Always use absolute file paths (e.g. /Users/you/images/photo.png).
• The agent maintains conversation history in interactive mode, so you can refer back to previous files.
• Multi-step operations (convert + resize) are handled automatically — the model chains tool calls internally.