bg-remove

name	bg-remove
description	Remove backgrounds from images using local AI (rembg). Use when removing backgrounds from character art, mascot images, photos, or any image that needs a transparent background.
user_invocable	true

Background Remove — Local AI Background Removal

Remove backgrounds from images using rembg (local, offline, no data sent externally). Outputs RGBA PNG with proper transparency.

Input

Arguments after /bg-remove:

• Source image path (required) — path to the image
• --trim (optional) — auto-trim transparent padding after removal
• --output <path> (optional) — custom output path. Default: same directory, <name>-transparent.png

Examples:

• /bg-remove assets/character/mascot.png
• /bg-remove image.png --trim
• /bg-remove image.png --output ~/Desktop/result.png

Setup

rembg is installed in a dedicated venv. Always activate it before use:

source ~/.claude/tools/rembg-env/bin/activate

If the venv doesn't exist, install it:

python3 -m venv ~/.claude/tools/rembg-env && source ~/.claude/tools/rembg-env/bin/activate && pip install "rembg[cpu,cli]"

Model files are cached in ~/.u2net/ (downloaded on first use per model, ~170MB for birefnet-general).

Process

Step 1: Verify Input

1. Check the source image exists
2. Get dimensions: sips -g pixelWidth -g pixelHeight <path>
3. View the image with the Read tool to understand what we're working with

Step 2: Remove Background

Use the birefnet-general model — validated in testing on illustrated/character art and general photos, producing clean edges across both.

source ~/.claude/tools/rembg-env/bin/activate && rembg i -m birefnet-general <input> <output>

Model choice: Default to birefnet-general. In side-by-side testing it gave clean edges on both illustrated subjects and photographic ones. Avoid anime-trained models (e.g. isnet-anime): on non-anime and even some illustrated inputs they tend to add artifacts and leave dark patches around edges. If birefnet-general underperforms on a specific image, compare against another general model rather than an anime-specific one.

Step 3: Verify Result

The Read tool renders transparency as black, so you MUST verify by compositing on a colored background:

source ~/.claude/tools/rembg-env/bin/activate && python3 -c "
from PIL import Image
import numpy as np

# Load result
img = Image.open('<output>').convert('RGBA')
alpha = np.array(img)[:,:,3]
total = alpha.size
transparent = np.sum(alpha == 0)
opaque = np.sum(alpha == 255)
print(f'Dimensions: {img.size}')
print(f'Transparent: {transparent/total*100:.1f}%')
print(f'Opaque: {opaque/total*100:.1f}%')
print(f'Corners alpha: TL={alpha[0,0]} TR={alpha[0,-1]} BL={alpha[-1,0]} BR={alpha[-1,-1]}')

# Composite on magenta for visual verification
bg = Image.new('RGBA', img.size, (255, 0, 255, 255))
bg.paste(img, (0, 0), img)
bg.save('<output_dir>/verify-magenta.png')
print('Verification image saved')
"

Then view the magenta verification image with the Read tool. The magenta should only show where background was removed.

Step 4: Optional Trim

If --trim was requested, trim transparent padding:

source ~/.claude/tools/rembg-env/bin/activate && python3 -c "
from PIL import Image
import numpy as np

img = Image.open('<output>').convert('RGBA')
alpha = np.array(img)[:,:,3]

# Find bounding box of non-transparent pixels
rows = np.any(alpha > 0, axis=1)
cols = np.any(alpha > 0, axis=0)
rmin, rmax = np.where(rows)[0][[0, -1]]
cmin, cmax = np.where(cols)[0][[0, -1]]

# Add small padding (2% of dimensions)
pad_h = max(int(img.height * 0.02), 4)
pad_w = max(int(img.width * 0.02), 4)
rmin = max(0, rmin - pad_h)
rmax = min(img.height - 1, rmax + pad_h)
cmin = max(0, cmin - pad_w)
cmax = min(img.width - 1, cmax + pad_w)

cropped = img.crop((cmin, rmin, cmax + 1, rmax + 1))
cropped.save('<output>')
print(f'Trimmed: {img.size} -> {cropped.size}')
"

Step 5: Report

Done: background removed
  Source: <input_path>
  Output: <output_path>
  Dimensions: <width>x<height>
  Transparent pixels: <percent>%
  Model: birefnet-general (local, offline)

Verify before shipping: open the output in Preview.app (or any viewer that shows the checkerboard pattern) to confirm real transparency. The Read tool renders transparency as solid black, so it cannot distinguish a transparent background from a black one — composite-over-a-color (Step 3) or a checkerboard viewer is the only reliable check.

Important Rules

1. Default to birefnet-general — in side-by-side testing it produced the cleanest edges on both illustrated and photographic inputs; anime-trained models added artifacts. Only switch models if it visibly underperforms on a specific image.
2. Always activate the venv before running rembg or Python with Pillow/numpy.
3. Always verify with magenta composite — don't trust the Read tool's rendering of transparency.
4. Never send images to external services — rembg runs 100% locally.
5. Preserve original files — output to a new file, never overwrite the source.
6. Clean up verification images — delete the magenta composite after confirming quality.