hashgraph-online/awesome-codex-plugins / plugins/Btike/bulk-bg-remove/skills/bulk-bg-remove
bulk-bg-remove
VerifiedRemove image backgrounds locally and in bulk: one photo, a folder (searched recursively) or many folders, with BiRefNet and lighter models picked to fit the machine. No uploads, no API keys, no per-image cost. Writes lossless transparent PNG/WebP, or shop-ready photos (white or any colour, square, sized, JPEG), to a new "<name>-no-bg" folder next to the input and never touches the originals. Use when the user asks to remove, cut out or erase a background, make a transparent PNG, isolate a product, person, animal or object, prepare product or catalog photos, or replace remove.bg for a batch. Reads JPG, PNG, HEIC, WebP, AVIF, TIFF and BMP.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.6 KB |
| agents/openai.yaml | config | 249 B |
| references/json-events.md | markdown | 6.1 KB |
| references/models.md | markdown | 7.5 KB |
| references/reviewer.md | markdown | 4.7 KB |
| references/troubleshooting.md | markdown | 2.5 KB |
references/troubleshooting.md
View on GitHub# Troubleshooting
## Install
- `bulk-bg-remove: command not found` after `uv tool install`: uv's tool folder
is not on PATH. Run `uv tool update-shell`, then open a new shell, or call it
through `uvx bulk-bg-remove …` for this session.
- uv picks a Python itself (3.11–3.13). If a corporate proxy blocks the download,
install Python 3.12 and run `uv tool install --python 3.12 bulk-bg-remove`.
## Model download
- The first run of a model downloads its weights to `~/.u2net/` (set `U2NET_HOME`
to move it). It needs network access once; after that everything is offline.
- A download cut halfway leaves a broken file: delete `~/.u2net/<model>.onnx`
and run again.
## RAM
- The plan refuses to start when free RAM is below what the model needs. Free
RAM is what the OS reports right now: closing browsers, IDEs and Docker
usually frees several GB.
- During a run, if free RAM drops below the reserve, new images wait (`paused`)
and continue when memory frees up (`resumed`). Nothing is lost.
- Very large photos (40+ MP) use more memory per image; the plan warns about it.
`--max-megapixels 24` runs the others now and lists the large ones to do later.
- `worker process was killed by the system (out of memory?)`: the OS stopped it,
usually for memory. Close apps and re-run the same command: done images are kept.
## Crashes
- `the CPU rejected an instruction (SIGILL)`: the machine's processor refused
code the libraries chose for it. This happens in Linux virtual machines on Apple
M4/M5 chips (Docker, UTM, Lima), which advertise SVE instructions the chip cannot
run. It is not a problem with the photos: run the skill on macOS directly, or on
a regular Linux machine.
## Images
- HEIC/HEIF and AVIF are read with pillow-heif and Pillow. `doctor` shows whether
they work on this machine (`checks.heic`, `checks.avif`).
- Files are recognised by content, not extension: a PNG named `.jpg` works, and a
web page saved as `.jpg` is skipped as "not an image".
- GIF, PDF and RAW camera files are not supported and are listed as skipped.
- Photos are rotated by their EXIF orientation first, so the output is upright.
- A photo with no clear subject (a landscape, a shelf full of products) can come
out mostly empty. The `job_done.note` field says when matting was skipped
because no foreground was found.
## Edges
- Hair or fur keeps a tint of the old background: re-run those images with
`--clean-edges --force`.
- Need speed over fine detail: `--fast-edges` skips edge matting.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |