v2.0.0 · MIT · macOS / Linux / Windows

Local-first
WordPress tooling.

Optimize images, manage posts, audit accessibility, and generate AI metadata for your WordPress media library — all from the terminal. Syncs to any WordPress site via the REST API.

$brew install gfargo/tap/localpress

Get started →GitHub

localpress list -i

localPress interactive media browser — navigate items, view details, and configure optimization from the terminal

Why localPress

WordPress media plugins charge monthly for what your laptop does for free

Smush, ShortPixel, Imagify — they all send your images to a remote server and bill you per-image or per-month. localPress processes everything on your own machine and syncs results back via the REST API.

Your hardware does the work

Cloud plugins charge $4–13/month for compute your laptop does for free.

State-of-the-art BiRefNet runs background removal on your M-series Mac in 1.5 seconds. ShortPixel charges 1 credit per image. You do the math.

Works with any WordPress host

EWWW needs exec() and shell access that most shared hosts block.

localPress talks to WordPress via Application Passwords (built into WP core since 5.6). Works on the cheapest shared host. Your laptop is the runtime.

Round-trip with real editors

No plugin lets you open an image in Photoshop, edit, and sync back.

Open in GIMP, Photoshop, or Preview. Save. It syncs back automatically. The workflow designers actually want — no one else offers it.

Built for AI agents

No image optimizer integrates with Claude, Cursor, or MCP-native agents.

First-party MCP server with 40+ typed tools. Drop one config block into your agent and it manages your entire media library autonomously.

See it in action

A full media manager in your terminal

localpress list -ilive

localPress interactive media browser — navigate through your WordPress media library, open detail views, and manage images from the terminal

Browse, inspect, and action your entire media library without leaving the terminal

Keyboard-driven overlays

Every action, one keystroke away

[o] optimize

localPress optimize settings — configure quality, format conversion, and replace-in-place from an inline overlay

Inline optimize settings — quality, format, replace mode

[/] search

Live search filters as you type

[c] convert

localPress format conversion — pick WebP, AVIF, JPEG, or PNG from a keyboard-driven picker

Format picker — WebP, AVIF, JPEG, PNG

[↵] details

localPress detail view — full metadata including dimensions, alt text, registered sizes, and processing status

Full metadata detail view

See it in action

Workflows, not screenshots

Actions tour

Every action at your fingertips — optimize, convert, resize

Full workflow

doctor → list → stats — the full localpress experience

What's inside

38 commands. One tool.

From a single image to your entire library — every operation is local, idempotent, and dry-run safe by default.

Processing

optimize

Compress without compromise

sharp + jSquash WASM codecs. Set a quality floor, pick a format, use named profiles, preview in the browser with --preview, or process your entire library in one pass.

$ localpress optimize --unoptimized --profile hero --apply

remove-bg

Background removal. No cloud.

Five ONNX models including state-of-the-art BiRefNet — all running on your hardware. Preview and tweak in the browser before applying.

$ localpress remove-bg 847 --model birefnet-lite --preview

Discovery

audit

Seven health checks, one command

Unoptimized, oversized, missing alt text, display-size mismatch, duplicate images, broken refs, orphaned files — surfaced in seconds.

$ localpress audit

$ export / importMigration

Backup, migrate, bulk-load.

Export your entire library as a ZIP with metadata manifest. Import directories or ZIPs with optional optimization on upload.

$ watchAutomation

Drop files. They appear in WordPress.

Watch a local directory for new or changed images — auto-optimizes and pushes to WordPress continuously.

$ editRound-trip

Open in any editor. Syncs back.

Download → GIMP, Photoshop, or Preview → save → automatically pushed to WordPress.

$ referencesDiscovery

Find every usage

Scan all posts for an attachment's URL. Rewrite them in-place after a rename or move.

Also included

initInteractive site wizard

sitesManage multiple sites

doctorCapability check + --fix

configProfiles + scalar values

listBrowse media library

showAttachment metadata

statsLibrary health dashboard

captionAI alt-text via Ollama (multilingual)

convertJPEG → WebP → AVIF

resizeResize preserving ratio

regenerateRebuild WP thumbnails

exportBackup as ZIP or directory

importBulk upload with optimize

postsContent CRUD (posts/pages/CPT)

a11yWCAG accessibility audit

pullDownload to local disk

pushUpload + replace-in-place

updateSelf-update localpress

completionsShell completions (bash/zsh/fish)

localPress audit

Seven health checks in a single pass

--unoptimizedImages never processed by localPress

--largeImages over a size threshold (default 1 MB)

--missing-altImages without alt text (accessibility / SEO)

--display-sizeImages larger than their biggest registered thumbnail

--duplicatesPerceptually identical images via dHash

--broken-refsAttachment URLs that return 404

--orphansFiles on disk with no DB record (requires WP-CLI)

localpress stats

Vision AI

Six fields, one vision model.

Same local Ollama vision model that powers caption now generates titles, descriptions, tags, image-type classifications, and AI-renamed slugs. Each is a dedicated command — or run them all at once with vision.

What it generates

localpress alt

Alt text

Concise single-sentence description for accessibility. Writes to alt_text.

localpress title

Title

3-7 word noun phrase. Auto-detects machine-generated names (Screenshot-…, IMG_…) for bulk cleanup.

localpress describe

Description

2-3 sentence description for galleries and attachment-page SEO. Writes to the description field.

localpress tag

Type

Detects screenshot/photo/illustration/diagram. Cached locally so optimize picks PNG vs WebP automatically.

localpress rename

Slug

AI-generated permalink slug (with --smart) or explicit (--to). Honest about file URL — slug only for v1.

Or — all at once

The vision workflow

localpress vision <id> runs all five generators in one pass. Print-only by default so you can review before writing. Pair with --apply to commit everything to WordPress in a single composed update.

Classification is cached locally — subsequent optimize calls on the same attachment automatically pick PNG for screenshots and WebP for photos.

# Print all five fields for review
localpress vision 2202

# Or write them all back at once
localpress vision 2202 --apply

# Or pick a subset
localpress vision 2202 --fields alt,title --apply

Commands reference →Ollama setup ↗

Time-machine

Always undoable.

Every destructive op writes a snapshot of the pre-change state before WordPress mutates. Wrong bulk optimize? Bad background removal? An agent that ran the wrong thing on 500 attachments? Walk it back with one command.

How it works

Run anything

Optimize, convert, resize, remove-bg, caption — bulk or single. Every destructive op writes a snapshot of the pre-change state to local storage before WordPress is touched.

localpress optimize --unoptimized --apply

Browse history

Every command creates a session. Inspect snapshots with `history`, or drop into the interactive TUI to walk through them.

localpress history -i

Undo the bad one

Dry-run first, apply when ready. Single attachment, whole session, or step back op-by-op. Works the same when an MCP agent drives it.

localpress undo --apply

Safe by default

Bulk undos dry-run unless you pass --apply, matching the rest of the CLI.

Bounded disk

Default 2 GB cap per site. Auto-prune on every op. Configurable via `history.maxSizeBytes`.

Idempotent-aware

Skipped ops (source unchanged) don't create snapshots. Re-running unchanged ops costs nothing.

MCP-first

Agents get `undo`, `history_list`, `history_show`, and `history_prune` as typed tools.

History & Undo guide →

Agent-native

Built for AI agents.

Drop one config block into Claude Desktop, Cursor, or any MCP client. 40+ typed tools cover every operation — from bulk optimization to accessibility audits. Same binary, new entrypoint. Agents manage your entire media library autonomously.

claude_desktop_config.json

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"]
    }
  }
}

claude — localpress MCP

AI agent using localpress MCP tools — lists unoptimized images and compresses them to WebP automatically

An AI agent finds and optimizes unoptimized images — no manual commands needed

40+ tools · 4 resources

Setup

sites_list
sites_use
sites_add
sites_remove
doctor
config_*

Discovery

list
show
stats
audit
references
watch_status

Vision AI

caption
generate_title
generate_description
tag
classify
vision

Processing

optimize
convert
resize
remove_bg
update_metadata

Library

pull
push
delete
rename
regenerate
export
import

Time-machine

history_list
history_show
history_prune
undo

Resources

localpress://siteslocalpress://statslocalpress://capabilitieslocalpress://history

MCP Setup guide →About the Model Context Protocol ↗

The full picture

How localPress stacks up

Feature-by-feature against the five most popular WordPress image optimization plugins.

Feature	localPress	EWWW	ShortPixel	Smush	Imagify
Processing location	Your laptop	WP server	Cloud	Cloud	Cloud
Recurring cost	$0	$0 – $25/mo	$4 – $10/mo	$3 – $13/mo	$6 – $12/mo
Works on shared host	✓	Needs exec()	✓	✓	✓
AI background removal	✓ local	✗	✓ paid	✗	✗
Desktop editor round-trip	✓	✗	✗	✗	✗
AI agent skill	✓	✗	✗	✗	✗
License	MIT	GPLv3	Proprietary	Mixed	Proprietary

Installation

Three ways to install

Homebrew — recommended

View tap ↗