AssetDiet MCP

AssetDiet

Asset intelligence for AI coding agents — audit, optimize, and roll back media safely.

One-Command Setup · Try With Your Agent · Code Migration · Supported Formats · Safety & Rollback · Docs

AI coding agents build frontend UIs in seconds, but treat media as opaque blobs — committing 4 MB raw camera photos, uncompressed SVGs, and duplicate icons straight into git. AssetDiet gives your agent eyes on media: auditing repos in milliseconds, executing lossless native optimizations, updating source code references, and keeping every byte reversible.

⚡ One-Command Setup

Connect AssetDiet to your AI coding assistant with zero manual configuration:

npx -y assetdiet-mcp@latest setup --yes

Automatically detects and registers AssetDiet with Cursor, Claude Desktop, Claude Code, Windsurf, and Codex with timestamped .bak configuration backups.

Real-World Results

public/hero.png          4.8 MB  →  642 KB   (−86.6%)   balanced
public/icons/logo.svg    184 KB  →   42 KB   (−77.2%)   safe
models/character.glb     8.6 MB  →  3.2 MB   (−62.8%)   balanced

🤖 Try This With Your Agent

Once configured, copy and paste this prompt into your AI coding assistant (Cursor Composer, Claude Code, Windsurf, or Claude Desktop):

Run an AssetDiet audit on this repo under the safe policy. Show me the top assets by potential savings, any exact duplicates, and a short optimization plan. Don't change any files yet.

Your agent will call assetdiet_audit, index SHA-256 hashes, surface duplicate groups, and outline a risk-free proposal before asking for your go-ahead.

💻 Or Run from Your Terminal

# 1. Read-only audit with instant savings & duplicate discovery
npx -y assetdiet-mcp@latest audit . --policy safe

# 2. Or get a concise 3-line scorecard summary
npx -y assetdiet-mcp@latest audit . --policy safe --summary

# 3. Apply lossless optimizations with atomic journal safety
npx -y assetdiet-mcp@latest optimize . --policy safe

git clone https://github.com/092Abdullah/AssetDiet.git
cd AssetDiet
pnpm install
pnpm build
pnpm test

🔗 Beyond Files: Codebase Reference Migration

Most optimizers only touch files on disk. AssetDiet can also update your code when formats change.

When converting heavy legacy formats (like .png to modern .webp or .avif), your agent uses AssetDiet's AST and regex reference engine:

• assetdiet_find_references: Traces every code, JSX, TS, CSS, and HTML reference to an asset across the repository.
• assetdiet_migrate_references: Atomically updates import statements and asset paths in your source files to match the new optimized filenames.

// Before
import hero from "./hero.png";
<img src="/assets/hero.png" />;

// After assetdiet_migrate_references
import hero from "./hero.webp";
<img src="/assets/hero.webp" />;

📦 Supported Asset Formats

AssetDiet uses battle-tested native engines and WebAssembly parsers. Zero cloud roundtrips.

🔄 How AssetDiet Works

1. Scan & Graph: Traverses repository files (respecting .gitignore, .assetdietignore, and standard build excludes), hashes content with SHA-256, and links code references.
2. Policy & Plan: Evaluates opportunities against your chosen policy (safe, balanced, or aggressive) and creates an in-memory execution plan.
3. Engine Optimization: Dispatches each asset to its native engine, writing to isolated temporary swap files (.tmp.<random>).
4. Verification & Commit: Deep-validates decodability and dimensions. On success, atomically swaps the file. On failure, discards the temporary file leaving your original intact.

🛡️ Safety & Atomic Rollback

Every file operation is 100% reversible:

1. Pre-Optimization Backups: Exact byte-for-byte originals are saved to .assetdiet/backups/<runId>/ before modification.
2. Write-Ahead Journal: State transitions are logged in .assetdiet/runs/<runId>.json.
3. Atomic Replacements: Uses OS-level atomic renames (fs.rename). Files are never partially overwritten.
4. Instant Restore:

   npx -y assetdiet-mcp@latest restore --run <runId>
   

🎯 Optimization Policy Matrix

📊 Real-World Results

AssetDiet benchmarked on typical web and game repository assets:

🔒 100% Local & Private

• Zero Telemetry: No analytics, tracking beacons, or phone-home pings.
• 100% Local Execution: All processing happens on your CPU using embedded native engines. Media never leaves your machine.
• Safe Agent Integration: Only concise text metadata is passed over local stdio to your assistant.

📚 Documentation

• CLI Reference — Commands for setup, doctor, audit, optimize, restore, and mcp.
• MCP Tools Reference — Complete specifications for all 16 Model Context Protocol tools.
• Configuration & Ignore Rules — Customizing .assetdietignore, policies, and assetdiet.config.json.
• Installation Guide — Global installation, manual configuration, and platform guides.
• Architecture — Monorepo design, self-contained distribution, and stdio isolation.
• Security Policy — Security practices and reporting.
• Changelog — Release history.

📄 License

MIT © 2026 AssetDiet Contributors