[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6JTP8NSVSBZMCPSVNXSJHGQ":3,"skill-same:01M6JTP8NSVSBZMCPSVNXSJHGQ":102},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":56,"commitSha":57,"skillDirectory":58,"forksCount":59,"repositoryHtmlUrl":60,"repositoryHomepageUrl":61,"ownerHtmlUrl":62,"ownerBlogUrl":63,"ownerDescription":64,"updatedAt":65,"install":66,"resources":79},"01M6JTP8NSVSBZMCPSVNXSJHGQ","bulk-bg-remove",null,"Remove 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\u002FWebP, or shop-ready photos (white or any colour, square, sized, JPEG), to a new \"\u003Cname>-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.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000031","产品经理","PROFESSION","适用职业",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"bulk bg remove","bulk","remove","uv","new","when","api keys","CPU","people","free","upgrade","next","image","ready","never","work","model","Bash","api","batch","product","support","2026-11-10 10:12:30",false,"---\nname: bulk-bg-remove\ndescription: >\n  Remove image backgrounds locally and in bulk: one photo, a folder (searched\n  recursively) or many folders, with BiRefNet and lighter models picked to fit\n  the machine. No uploads, no API keys, no per-image cost. Writes lossless\n  transparent PNG\u002FWebP, or shop-ready photos (white or any colour, square,\n  sized, JPEG), to a new \"\u003Cname>-no-bg\" folder next to the input and never\n  touches the originals. Use when the user asks to remove, cut out or\n  erase a background, make a transparent PNG, isolate a product, person, animal\n  or object, prepare product or catalog photos, or replace remove.bg for a\n  batch. Reads JPG, PNG, HEIC, WebP, AVIF, TIFF and BMP.\nlicense: MIT\ncompatibility: >\n  Needs uv (installs the engine and a matching Python 3.11-3.13 by itself).\n  macOS, Linux and Windows; runs on the CPU (no GPU support yet). Product\n  photos work from ~3.5 GB of free RAM (best results from ~12 GB); hair, fur,\n  people and busy scenes need ~14.5 GB for the best model. Each model\n  downloads once (40 MB to 1 GB).\nallowed-tools: Bash(bulk-bg-remove:*) Bash(uv tool install bulk-bg-remove*) Bash(uv tool upgrade bulk-bg-remove*)\nmetadata:\n  version: \"0.1.3\"\n---\n\n# bulk-bg-remove\n\nCut out the subject of every image the user points at, on this machine. The\nengine is the `bulk-bg-remove` command: it scans, picks a model that fits the\nfree RAM, plans the run, processes the images and verifies every output. You\ndrive it with `--json` (one JSON object per line) and report back.\n\nRun every command on its own: no `;`, `&&` or pipes. Harnesses approve shell\ncommands one at a time, and this skill pre-approves only `bulk-bg-remove …`\nand `uv tool install|upgrade bulk-bg-remove`, so a chained command stops for\napproval (or fails in a session nobody is watching).\n\n## 1. Make sure the engine is installed\n\n```bash\nbulk-bg-remove --version\n```\n\n- Not found: run `uv tool install bulk-bg-remove` straight away (no need to\n  check uv first: if uv is missing, that command says so).\n- No `uv` either: stop and ask the user to install uv\n  (https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F), then retry. Do not\n  run a remote install script without the user's OK. `pipx install bulk-bg-remove`\n  also works.\n- Older than this skill's `metadata.version`: `uv tool upgrade bulk-bg-remove`.\n- Options and model names: `bulk-bg-remove --help`.\n\n## 2. Look at the images, then plan\n\n```bash\nbulk-bg-remove \"\u003Cpath>\" --dry-run --sample-sheet --json\n```\n\nAdd `--profile \u003Cname>` right away if the user's words already say what the\nimages are. The dry-run loads no model and writes nothing next to the photos\n(the sheet goes to a temporary folder; no need to mention or delete it). Read\nthe events:\n\n- `scan.inventory`: images found, formats, and `skipped` (not images, hidden\n  image files, earlier `-no-bg` output folders) with a reason each.\n- `sample_sheet.path`: a contact sheet of up to 12 of the images. **Open it and\n  look.** Pick the profile that fits most of them:\n\n  | Profile | The images are mostly |\n  |---|---|\n  | `uniform` (default) | products and objects with clean outlines: bottles, boxes, shoes, tools, furniture |\n  | `complex` | hair, fur, plants, wires, thin or see-through parts |\n  | `people` | portraits or groups of people |\n  | `scene` | cluttered scenes with no clean background |\n  | `drawing` | cartoons, anime, flat illustration |\n\n  The user's own words win over the sheet (\"these are product shots\"). With no\n  clear majority, choose by the hardest part: any hair or fur → `complex`, even\n  for portraits. If a folder really mixes kinds (products and portraits), offer\n  to run its sub-folders separately with their own profiles.\n- `plan`: `model` (what `auto` picked), `model_choice` (its score against the\n  best model for that profile, and the RAM the best one needs), `eta_seconds`,\n  `blockers`. If you picked a different profile than the first dry-run used,\n  dry-run again with `--profile \u003Cname>` (no `--sample-sheet` needed).\n\n**What the output is for.** Transparent cut-outs are the default. When the\nuser's words point to a shop (store, marketplace, Amazon, Shopify, catalogue,\n\"white background\", \"square\"), add the finishing flags to the run:\n\n| They want | Flags |\n|---|---|\n| Photos for a shop or marketplace | `--shop`: white, square, product filling ~85%, 2000 px, JPEG |\n| A brand colour behind the product | `--background \"#RRGGBB\"` (plus `--square`, `--pad PCT`, `--size PX` as needed) |\n| Transparent, but square and trimmed | `--square --pad 5` |\n\nA shop with no further detail means `--shop`: do not stop to ask. Say in the\nreport that transparent cut-outs or a brand colour are one flag away.\n\n## 3. Run\n\nIf `plan.blockers` is empty, start right away, no need to ask:\n\n```bash\nbulk-bg-remove \"\u003Cpath>\" --profile \u003Cprofile> [finishing flags] --review-sheets --json --yes\n```\n\n- `--yes` only skips the engine's own \"Start?\" prompt.\n- Read the events from the command's own output; do not redirect it to a\n  file (writing outside the project folder needs extra approval).\n- stdout is pure JSON. stderr may show library warnings; judge the run by the\n  exit code and the `finished` event. `worker_loading`\u002F`worker_ready` can repeat\n  mid-run when RAM is low (a worker restarting to free memory): not a crash.\n- If `plan.eta_seconds` is over ~120, run it in the background if your harness\n  allows, and report progress now and then from `job_done` events\n  (`done`\u002F`total`, `source`). Read a background run's output file with your\n  file-reading tool, not with a shell command (`python`, `tail`…), which needs\n  extra approval.\n- Output: `shoe.jpg` → `shoe-no-bg\u002Fshoe.png` (`.jpg` with `--shop`); `products\u002F` → `products-no-bg\u002F`\n  with sub-folders mirrored, next to the input. `-o DIR` overrides it. If two\n  inputs share a name (`product.jpg` + `product.png`), both get their extension\n  added (`product_jpg.png`, `product_png.png`); `job_started.destination` has\n  the final name.\n- Images already done are skipped on a re-run; `--force` redoes them. Changing\n  the finishing flags (another colour, size or margin) redoes them by itself.\n\nExit codes: `0` all good · `1` some images failed, or the model could not be\nprepared (see the `error` event) · `2` blocked by the plan · `130` interrupted.\n\n## When the plan is blocked\n\nNever work around a blocker on your own. Tell the user, in plain words, and\noffer the choices:\n\n- **The best model does not fit, a weaker one does** (the blocker mentions\n  `--allow-fallback`): for this kind of image the light model is clearly worse\n  (e.g. hair or plants: about 5\u002F10 instead of 7.6\u002F10). Offer: close some apps\n  and retry, or go ahead with the lighter model by adding `--allow-fallback`.\n  If the user asked for the best quality, say that the lighter model goes\n  against it.\n- **Not enough free RAM for any model**: say how much is free and how much the\n  lightest model needs, then offer the ways to fit, checking each with a\n  `--dry-run` before you suggest it (one per dry-run, `plan.blockers` empty means\n  it fits):\n  1. **Close some apps** (browsers, Docker, video tools) and retry: no quality lost.\n  2. **`--fast-edges`**: skips edge matting, which needs the most RAM per image.\n     Fine for products; hair, fur and plants come out coarser, so say so.\n  3. **Large photos apart**: if `scan.inventory.max_megapixels` is high (20+),\n     `--max-megapixels 24` (or lower) does the rest now; the large ones are\n     listed as skipped with that reason. Run them later on their own, after\n     closing apps or with `--fast-edges`.\n  4. **Without the finishing** (`--shop`, `--background`, `--size`…), if that is\n     what tips it over: transparent cut-outs now. Say plainly that adding the\n     finish later means another run that needs the same RAM as this one.\n  If `scan.hardware.ram_total_gb` itself is below what the lightest model needs\n  even with these, closing apps cannot fix it: say this machine cannot run it.\n- **Not enough disk**: say how much is needed and where.\n- **No supported images**: say what was skipped and why.\n\nThe plan is the authority on RAM; `doctor` is only a quick check. Do not lower\n`--min-free-ram` to force a start: the machine would swap.\n\nWhen the model is lighter but within half a point of the best (for example\nproduct photos on a laptop with little free RAM), `auto` uses it on its own;\nmention it in one line of your report.\n\n**\"Best quality\"** needs no extra flag: keep `--model auto`, never add\n`--fast-edges`, and check `model_choice.gap == 0` (the best model for that\nprofile is running). If the gap is above 0, say so and offer to free RAM.\n\n## 4. Review the cut-outs\n\nThe engine checks files, not looks. `--review-sheets` (step 3) adds a\n`review_sheets` event just before `finished`: sheet PNGs in a temporary folder,\neach showing up to 12 cut-outs numbered `#n`, as original | on black | on white.\nWith a `--background` they still show the transparent cut-out (a leftover of a\nwhite background would be invisible on white); the finish itself is mechanical.\n\nThe sheets hold only the cut-outs that need eyes. A cut-out whose photo has a\nplain background and that matches it exactly (nothing unlike the background\nremoved, no background colour left on the edge, the same mask on the mirrored\nphoto, and more: see `job_done.check`) is **certified** (`job_done.certified`)\nand left off the sheets, except 1 in 20 kept as an `AUDIT` entry\n(`review_sheets.audit`). Hair, fur, glass and busy backgrounds are never\ncertified; a white or clear product on white only when its whole outline still\nstands out from the backdrop, so most of them are reviewed. If the user wants every\ncut-out reviewed anyway, add `--review-all` to the run.\n\n1. **Get a fresh pair of eyes.** If you can start a subagent (Claude Code: the\n   `bg-reviewer` agent this plugin ships, or any subagent; Codex: a sub-agent),\n   give it the sheet paths, the `review_sheets` event (it has each image's\n   `zoom` close-up) and the full text of\n   `references\u002Freviewer.md`. It did not run the batch, so it sees what is\n   there, not what you expect. With more than 4 sheets, split them across\n   several reviewers in parallel: looking costs no engine RAM. If you cannot\n   start one, review the sheets yourself with `references\u002Freviewer.md`.\n2. **Fix once, on the side.** For each `fix`, take the `source` of its `n`\n   from the `review_sheets` event and run again into a retry folder next to\n   the output, named so later scans skip it (`products\u002F` → output\n   `products-no-bg\u002F`, retries `products-retry-no-bg\u002F`), one run per set of\n   flags, never two at once:\n\n   ```bash\n   bulk-bg-remove \"\u003Cpath>\" -o \"\u003Cname>-retry-no-bg\" --profile \u003Cprofile> --only \u003Csource> [--only \u003Csource> ...] \u003Cfix flags> [finishing flags] --review-sheets --review-all --json --yes\n   ```\n\n   Keep the first run's finishing flags (`--shop`, `--background`…) so the\n   new file can replace the old one, and keep `--review-all`: every redo must\n   reach the sheets to be compared, even one that now passes certification.\n\n   `--only` takes the absolute `source`, a path relative to `\u003Cpath>`, or a bare\n   file name if it is unique, and keeps the usual output names (the same\n   `label` as on the first sheets). A fix whose plan is blocked (e.g. `--profile\n   complex` needs more RAM) goes through \"When the plan is blocked\".\n3. **Keep the better one.** Give the reviewer the new sheets plus the earlier\n   ones and ask it to compare (see \"Comparing a fix\" in `reviewer.md`). Copy a\n   new cut-out over the first one (same `label` under the output folder) only\n   when the reviewer says `keep: new`; a\n   second pass can make a good cut-out worse. One round only: anything still\n   wrong, and every `ask`, goes in your report with the sheet path so the user\n   can see it. Mention the retry folder: the user can delete it.\n\nIf a reviewer flags an `AUDIT` entry, the certification missed a defect on these\nphotos: say so in the report and offer to re-run the batch with `--force\n--review-sheets --review-all` (every cut-out reviewed).\n\nReview by default; skip it only if the user wants speed over checking or says\nnot to. The sheets cover the images this run processed: on a re-run where\neverything was already done there is no `review_sheets` event.\n\n## 5. Report back\n\nFrom the final `finished` event:\n\n- **Done**: `processed` images in `output`. Mention any renamed output.\n- **Failed** (`failed`): one line each, in plain words. `image file is\n  truncated` or `cannot identify image` → the file is damaged; re-export or\n  re-download it. Do not retry the same file in a loop.\n- **Not processed** (`not_processed` and `scan.inventory.skipped`): group by\n  reason (\"3 files are not images: notes.txt, fake.pdf, page.jpg\"); collapse\n  long lists. Always mention hidden image files and earlier `-no-bg` folders if\n  the user said \"all the photos\".\n- **Warnings** (`warnings`, and `job_done.note`): `empty cut-out` (no subject\n  found) and `nothing removed` deserve a line each; `edge matting skipped` means\n  that image probably came out empty or ghostly; `edge matting at N MP to fit\n  free RAM` means its edges are a bit softer than usual; `upscaled ×N from a\n  small original` means a shop photo was enlarged and may look soft: suggest a\n  bigger original.\n\nDo not claim success for images listed in `failed`. `processed` counts only\noutputs the engine verified (a readable file of the expected kind and size; an\nempty or unchanged cut-out is listed in `warnings`), so no extra check is\nneeded for the report. A good report is 3-5 lines:\n\n> Done: 37 of 38 photos cut out, in `~\u002FPictures\u002Fproducts-no-bg\u002F` (transparent\n> PNG, same size, originals untouched). Model: birefnet-general-lite.\n> 1 failed: `IMG_0042.jpg` is damaged, re-export it.\n> 2 files skipped: not images (notes.txt, list.pdf).\n> Review: 35 fine; 2 had a green fringe on the hair and were redone with\n> `--clean-edges`, now fine.\n\n**Store and catalog photos.** Say what the output is. Transparent: the same\nsize as the original; offer `--shop` (white, square, 2000 px JPEG) or a brand\ncolour if their shop needs it. With `--shop`: ready to upload. Either way,\ncontact shadows under the product are removed; the engine does not add a\nshadow.\n\n## Options worth knowing\n\n| Flag | Use it when |\n|---|---|\n| `--profile NAME` | Always, from step 2. |\n| `--review-sheets` | Always, unless the user wants speed over checking (step 4). |\n| `--only FILE` | Redoing chosen images after a review (step 4), with `-o` to a temporary folder. Implies `--force` for them. |\n| `--model NAME` | The user names a model, or `references\u002Fmodels.md` says so for a special case. Default `auto`. |\n| `--format webp` | The user wants smaller files (still lossless). Default PNG. |\n| `--shop` | Photos for a shop or marketplace: `--background white --square --pad 7.5 --size 2000 --format jpg`; any of them can be overridden. |\n| `--background COLOUR` | `white`, `black` or `#RRGGBB` behind the product. Needed for `--format jpg`. The hex is painted in the photo's own colour profile: on wide-gamut (Display P3) photos a brand colour can look slightly off; white and black are exact. |\n| `--square` · `--pad PCT` · `--size PX` | Square canvas around the subject · margin on each side, % of the canvas · longest side in pixels. |\n| `--clean-edges` | A coloured halo from the old background shows on hair or fur (green screen, strong colours). Recolours semi-transparent edge pixels only. |\n| `--fast-edges` | Speed matters more than hair and fur detail. Never when the user asked for the best quality. |\n| `-o DIR` | The user wants the output somewhere specific. |\n\nThe subject's pixels are copied bit for bit (except with `--clean-edges`, and\nonly on edge pixels), and the output keeps the input's exact size. Finishing\nis the opt-in exception: `--background` blends only the edge pixels, `--square`\nand `--pad` crop, `--size` resamples, and JPEG is lossy (quality 95). No model\nkeeps clear glass see-through; warn the user if the photos are glassware on a\ncoloured background.\n\n## Checking the machine\n\n`bulk-bg-remove doctor --json` prints one object: `ready`, `checks` (HEIC,\nAVIF, WebP support, free RAM), `auto` (the model `auto` would pick right now\nfor each profile) and `models` (each model's RAM need and whether it fits).\nIt exits 2 when not ready; `checks` says why. A missing HEIC or AVIF check only\nmatters if the folder has those files.\n\n## For people, not agents\n\nIf the user would rather drag and drop photos themselves, tell them to run\n`bulk-bg-remove` with no arguments: it opens a local page in the browser where\nthey can drop files or folders or paste images. Output lands in\n`~\u002FDownloads\u002F\u003Cname>-no-bg\u002F`.\n\n## References\n\n- `references\u002Fmodels.md`: every model's scores by kind of image, speed and RAM.\n- `references\u002Freviewer.md`: how to review the cut-outs, the defects and their fixes.\n- `references\u002Fjson-events.md`: every `--json` event and its fields.\n- `references\u002Ftroubleshooting.md`: install, model download, RAM and format problems.\n","# bulk-bg-remove\n\nCut out the subject of every image the user points at, on this machine. The\nengine is the `bulk-bg-remove` command: it scans, picks a model that fits the\nfree RAM, plans the run, processes the images and verifies every output. You\ndrive it with `--json` (one JSON object per line) and report back.\n\nRun every command on its own: no `;`, `&&` or pipes. Harnesses approve shell\ncommands one at a time, and this skill pre-approves only `bulk-bg-remove …`\nand `uv tool install|upgrade bulk-bg-remove`, so a chained command stops for\napproval (or fails in a session nobody is watching).\n\n## 1. Make sure the engine is installed\n\n```bash\nbulk-bg-remove --version\n```\n\n- Not found: run `uv tool install bulk-bg-remove` straight away (no need to\n  check uv first: if uv is missing, that command says so).\n- No `uv` either: stop and ask the user to install uv\n  (https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F), then retry. Do not\n  run a remote install script without the user's OK. `pipx install bulk-bg-remove`\n  also works.\n- Older than this skill's `metadata.version`: `uv tool upgrade bulk-bg-remove`.\n- Options and model names: `bulk-bg-remove --help`.\n\n## 2. Look at the images, then plan\n\n```bash\nbulk-bg-remove \"\u003Cpath>\" --dry-run --sample-sheet --json\n```\n\nAdd `--profile \u003Cname>` right away if the user's words already say what the\nimages are. The dry-run loads no model and writes nothing next to the photos\n(the sheet goes to a temporary folder; no need to mention or delete it). Read\nthe events:\n\n- `scan.inventory`: images found, formats, and `skipped` (not images, hidden\n  image files, earlier `-no-bg` output folders) with a reason each.\n- `sample_sheet.path`: a contact sheet of up to 12 of the images. **Open it and\n  look.** Pick the profile that fits most of them:\n\n  | Profile | The images are mostly |\n  |---|---|\n  | `uniform` (default) | products and objects with clean outlines: bottles, boxes, shoes, tools, furniture |\n  | `complex` | hair, fur, plants, wires, thin or see-through parts |\n  | `people` | portraits or groups of people |\n  | `scene` | cluttered scenes with no clean background |\n  | `drawing` | cartoons, anime, flat illustration |\n\n  The user's own words win over the sheet (\"these are product shots\"). With no\n  clear majority, choose by the hardest part: any hair or fur → `complex`, even\n  for portraits. If a folder really mixes kinds (products and portraits), offer\n  to run its sub-folders separately with their own profiles.\n- `plan`: `model` (what `auto` picked), `model_choice` (its score against the\n  best model for that profile, and the RAM the best one needs), `eta_seconds`,\n  `blockers`. If you picked a different profile than the first dry-run used,\n  dry-run again with `--profile \u003Cname>` (no `--sample-sheet` needed).\n\n**What the output is for.** Transparent cut-outs are the default. When the\nuser's words point to a shop (store, marketplace, Amazon, Shopify, catalogue,\n\"white background\", \"square\"), add the finishing flags to the run:\n\n| They want | Flags |\n|---|---|\n| Photos for a shop or marketplace | `--shop`: white, square, product filling ~85%, 2000 px, JPEG |\n| A brand colour behind the product | `--background \"#RRGGBB\"` (plus `--square`, `--pad PCT`, `--size PX` as needed) |\n| Transparent, but square and trimmed | `--square --pad 5` |\n\nA shop with no further detail means `--shop`: do not stop to ask. Say in the\nreport that transparent cut-outs or a brand colour are one flag away.\n\n## 3. Run\n\nIf `plan.blockers` is empty, start right away, no need to ask:\n\n```bash\nbulk-bg-remove \"\u003Cpath>\" --profile \u003Cprofile> [finishing flags] --review-sheets --json --yes\n```\n\n- `--yes` only skips the engine's own \"Start?\" prompt.\n- Read the events from the command's own output; do not redirect it to a\n  file (writing outside the project folder needs extra approval).\n- stdout is pure JSON. stderr may show library warnings; judge the run by the\n  exit code and the `finished` event. `worker_loading`\u002F`worker_ready` can repeat\n  mid-run when RAM is low (a worker restarting to free memory): not a crash.\n- If `plan.eta_seconds` is over ~120, run it in the background if your harness\n  allows, and report progress now and then from `job_done` events\n  (`done`\u002F`total`, `source`). Read a background run's output file with your\n  file-reading tool, not with a shell command (`python`, `tail`…), which needs\n  extra approval.\n- Output: `shoe.jpg` → `shoe-no-bg\u002Fshoe.png` (`.jpg` with `--shop`); `products\u002F` → `products-no-bg\u002F`\n  with sub-folders mirrored, next to the input. `-o DIR` overrides it. If two\n  inputs share a name (`product.jpg` + `product.png`), both get their extension\n  added (`product_jpg.png`, `product_png.png`); `job_started.destination` has\n  the final name.\n- Images already done are skipped on a re-run; `--force` redoes them. Changing\n  the finishing flags (another colour, size or margin) redoes them by itself.\n\nExit codes: `0` all good · `1` some images failed, or the model could not be\nprepared (see the `error` event) · `2` blocked by the plan · `130` interrupted.\n\n## When the plan is blocked\n\nNever work around a blocker on your own. Tell the user, in plain words, and\noffer the choices:\n\n- **The best model does not fit, a weaker one does** (the blocker mentions\n  `--allow-fallback`): for this kind of image the light model is clearly worse\n  (e.g. hair or plants: about 5\u002F10 instead of 7.6\u002F10). Offer: close some apps\n  and retry, or go ahead with the lighter model by adding `--allow-fallback`.\n  If the user asked for the best quality, say that the lighter model goes\n  against it.\n- **Not enough free RAM for any model**: say how much is free and how much the\n  lightest model needs, then offer the ways to fit, checking each with a\n  `--dry-run` before you suggest it (one per dry-run, `plan.blockers` empty means\n  it fits):\n  1. **Close some apps** (browsers, Docker, video tools) and retry: no quality lost.\n  2. **`--fast-edges`**: skips edge matting, which needs the most RAM per image.\n     Fine for products; hair, fur and plants come out coarser, so say so.\n  3. **Large photos apart**: if `scan.inventory.max_megapixels` is high (20+),\n     `--max-megapixels 24` (or lower) does the rest now; the large ones are\n     listed as skipped with that reason. Run them later on their own, after\n     closing apps or with `--fast-edges`.\n  4. **Without the finishing** (`--shop`, `--background`, `--size`…), if that is\n     what tips it over: transparent cut-outs now. Say plainly that adding the\n     finish later means another run that needs the same RAM as this one.\n  If `scan.hardware.ram_total_gb` itself is below what the lightest model needs\n  even with these, closing apps cannot fix it: say this machine cannot run it.\n- **Not enough disk**: say how much is needed and where.\n- **No supported images**: say what was skipped and why.\n\nThe plan is the authority on RAM; `doctor` is only a quick check. Do not lower\n`--min-free-ram` to force a start: the machine would swap.\n\nWhen the model is lighter but within half a point of the best (for example\nproduct photos on a laptop with little free RAM), `auto` uses it on its own;\nmention it in one line of your report.\n\n**\"Best quality\"** needs no extra flag: keep `--model auto`, never add\n`--fast-edges`, and check `model_choice.gap == 0` (the best model for that\nprofile is running). If the gap is above 0, say so and offer to free RAM.\n\n## 4. Review the cut-outs\n\nThe engine checks files, not looks. `--review-sheets` (step 3) adds a\n`review_sheets` event just before `finished`: sheet PNGs in a temporary folder,\neach showing up to 12 cut-outs numbered `#n`, as original | on black | on white.\nWith a `--background` they still show the transparent cut-out (a leftover of a\nwhite background would be invisible on white); the finish itself is mechanical.\n\nThe sheets hold only the cut-outs that need eyes. A cut-out whose photo has a\nplain background and that matches it exactly (nothing unlike the background\nremoved, no background colour left on the edge, the same mask on the mirrored\nphoto, and more: see `job_done.check`) is **certified** (`job_done.certified`)\nand left off the sheets, except 1 in 20 kept as an `AUDIT` entry\n(`review_sheets.audit`). Hair, fur, glass and busy backgrounds are never\ncertified; a white or clear product on white only when its whole outline still\nstands out from the backdrop, so most of them are reviewed. If the user wants every\ncut-out reviewed anyway, add `--review-all` to the run.\n\n1. **Get a fresh pair of eyes.** If you can start a subagent (Claude Code: the\n   `bg-reviewer` agent this plugin ships, or any subagent; Codex: a sub-agent),\n   give it the sheet paths, the `review_sheets` event (it has each image's\n   `zoom` close-up) and the full text of\n   `references\u002Freviewer.md`. It did not run the batch, so it sees what is\n   there, not what you expect. With more than 4 sheets, split them across\n   several reviewers in parallel: looking costs no engine RAM. If you cannot\n   start one, review the sheets yourself with `references\u002Freviewer.md`.\n2. **Fix once, on the side.** For each `fix`, take the `source` of its `n`\n   from the `review_sheets` event and run again into a retry folder next to\n   the output, named so later scans skip it (`products\u002F` → output\n   `products-no-bg\u002F`, retries `products-retry-no-bg\u002F`), one run per set of\n   flags, never two at once:\n\n   ```bash\n   bulk-bg-remove \"\u003Cpath>\" -o \"\u003Cname>-retry-no-bg\" --profile \u003Cprofile> --only \u003Csource> [--only \u003Csource> ...] \u003Cfix flags> [finishing flags] --review-sheets --review-all --json --yes\n   ```\n\n   Keep the first run's finishing flags (`--shop`, `--background`…) so the\n   new file can replace the old one, and keep `--review-all`: every redo must\n   reach the sheets to be compared, even one that now passes certification.\n\n   `--only` takes the absolute `source`, a path relative to `\u003Cpath>`, or a bare\n   file name if it is unique, and keeps the usual output names (the same\n   `label` as on the first sheets). A fix whose plan is blocked (e.g. `--profile\n   complex` needs more RAM) goes through \"When the plan is blocked\".\n3. **Keep the better one.** Give the reviewer the new sheets plus the earlier\n   ones and ask it to compare (see \"Comparing a fix\" in `reviewer.md`). Copy a\n   new cut-out over the first one (same `label` under the output folder) only\n   when the reviewer says `keep: new`; a\n   second pass can make a good cut-out worse. One round only: anything still\n   wrong, and every `ask`, goes in your report with the sheet path so the user\n   can see it. Mention the retry folder: the user can delete it.\n\nIf a reviewer flags an `AUDIT` entry, the certification missed a defect on these\nphotos: say so in the report and offer to re-run the batch with `--force\n--review-sheets --review-all` (every cut-out reviewed).\n\nReview by default; skip it only if the user wants speed over checking or says\nnot to. The sheets cover the images this run processed: on a re-run where\neverything was already done there is no `review_sheets` event.\n\n## 5. Report back\n\nFrom the final `finished` event:\n\n- **Done**: `processed` images in `output`. Mention any renamed output.\n- **Failed** (`failed`): one line each, in plain words. `image file is\n  truncated` or `cannot identify image` → the file is damaged; re-export or\n  re-download it. Do not retry the same file in a loop.\n- **Not processed** (`not_processed` and `scan.inventory.skipped`): group by\n  reason (\"3 files are not images: notes.txt, fake.pdf, page.jpg\"); collapse\n  long lists. Always mention hidden image files and earlier `-no-bg` folders if\n  the user said \"all the photos\".\n- **Warnings** (`warnings`, and `job_done.note`): `empty cut-out` (no subject\n  found) and `nothing removed` deserve a line each; `edge matting skipped` means\n  that image probably came out empty or ghostly; `edge matting at N MP to fit\n  free RAM` means its edges are a bit softer than usual; `upscaled ×N from a\n  small original` means a shop photo was enlarged and may look soft: suggest a\n  bigger original.\n\nDo not claim success for images listed in `failed`. `processed` counts only\noutputs the engine verified (a readable file of the expected kind and size; an\nempty or unchanged cut-out is listed in `warnings`), so no extra check is\nneeded for the report. A good report is 3-5 lines:\n\n> Done: 37 of 38 photos cut out, in `~\u002FPictures\u002Fproducts-no-bg\u002F` (transparent\n> PNG, same size, originals untouched). Model: birefnet-general-lite.\n> 1 failed: `IMG_0042.jpg` is damaged, re-export it.\n> 2 files skipped: not images (notes.txt, list.pdf).\n> Review: 35 fine; 2 had a green fringe on the hair and were redone with\n> `--clean-edges`, now fine.\n\n**Store and catalog photos.** Say what the output is. Transparent: the same\nsize as the original; offer `--shop` (white, square, 2000 px JPEG) or a brand\ncolour if their shop needs it. With `--shop`: ready to upload. Either way,\ncontact shadows under the product are removed; the engine does not add a\nshadow.\n\n## Options worth knowing\n\n| Flag | Use it when |\n|---|---|\n| `--profile NAME` | Always, from step 2. |\n| `--review-sheets` | Always, unless the user wants speed over checking (step 4). |\n| `--only FILE` | Redoing chosen images after a review (step 4), with `-o` to a temporary folder. Implies `--force` for them. |\n| `--model NAME` | The user names a model, or `references\u002Fmodels.md` says so for a special case. Default `auto`. |\n| `--format webp` | The user wants smaller files (still lossless). Default PNG. |\n| `--shop` | Photos for a shop or marketplace: `--background white --square --pad 7.5 --size 2000 --format jpg`; any of them can be overridden. |\n| `--background COLOUR` | `white`, `black` or `#RRGGBB` behind the product. Needed for `--format jpg`. The hex is painted in the photo's own colour profile: on wide-gamut (Display P3) photos a brand colour can look slightly off; white and black are exact. |\n| `--square` · `--pad PCT` · `--size PX` | Square canvas around the subject · margin on each side, % of the canvas · longest side in pixels. |\n| `--clean-edges` | A coloured halo from the old background shows on hair or fur (green screen, strong colours). Recolours semi-transparent edge pixels only. |\n| `--fast-edges` | Speed matters more than hair and fur detail. Never when the user asked for the best quality. |\n| `-o DIR` | The user wants the output somewhere specific. |\n\nThe subject's pixels are copied bit for bit (except with `--clean-edges`, and\nonly on edge pixels), and the output keeps the input's exact size. Finishing\nis the opt-in exception: `--background` blends only the edge pixels, `--square`\nand `--pad` crop, `--size` resamples, and JPEG is lossy (quality 95). No model\nkeeps clear glass see-through; warn the user if the photos are glassware on a\ncoloured background.\n\n## Checking the machine\n\n`bulk-bg-remove doctor --json` prints one object: `ready`, `checks` (HEIC,\nAVIF, WebP support, free RAM), `auto` (the model `auto` would pick right now\nfor each profile) and `models` (each model's RAM need and whether it fits).\nIt exits 2 when not ready; `checks` says why. A missing HEIC or AVIF check only\nmatters if the folder has those files.\n\n## For people, not agents\n\nIf the user would rather drag and drop photos themselves, tell them to run\n`bulk-bg-remove` with no arguments: it opens a local page in the browser where\nthey can drop files or folders or paste images. Output lands in\n`~\u002FDownloads\u002F\u003Cname>-no-bg\u002F`.\n\n## References\n\n- `references\u002Fmodels.md`: every model's scores by kind of image, speed and RAM.\n- `references\u002Freviewer.md`: how to review the cut-outs, the defects and their fixes.\n- `references\u002Fjson-events.md`: every `--json` event and its fields.\n- `references\u002Ftroubleshooting.md`: install, model download, RAM and format problems.\n",{"name":5,"license":15,"metadata":51,"description":53,"allowed-tools":54,"compatibility":55},{"version":52},"0.1.3","Remove 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\u002FWebP, or shop-ready photos (white or any colour, square, sized, JPEG), to a new \"\u003Cname>-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.\n","Bash(bulk-bg-remove:*) Bash(uv tool install bulk-bg-remove*) Bash(uv tool upgrade bulk-bg-remove*)","Needs uv (installs the engine and a matching Python 3.11-3.13 by itself). macOS, Linux and Windows; runs on the CPU (no GPU support yet). Product photos work from ~3.5 GB of free RAM (best results from ~12 GB); hair, fur, people and busy scenes need ~14.5 GB for the best model. Each model downloads once (40 MB to 1 GB).\n","main","b0f0a87593c578a7898eccaf1b363f7f87c1f99b","plugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":67,"prompt":77,"zipAvailable":78},[68,71,74],{"tool":69,"command":70},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill bulk-bg-remove",{"tool":72,"command":73},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill bulk-bg-remove",{"tool":75,"command":76},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill bulk-bg-remove","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002FSKILL.md",true,[80,86,90,94,98],{"path":81,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":84,"sourceHtmlUrl":85},"agents\u002Fopenai.yaml","REFERENCE","参考文档",249,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002Fagents\u002Fopenai.yaml",{"path":87,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fjson-events.md",6282,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002Freferences\u002Fjson-events.md",{"path":91,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fmodels.md",7692,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002Freferences\u002Fmodels.md",{"path":95,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Freviewer.md",4784,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002Freferences\u002Freviewer.md",{"path":99,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Ftroubleshooting.md",2534,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FBtike\u002Fbulk-bg-remove\u002Fskills\u002Fbulk-bg-remove\u002Freferences\u002Ftroubleshooting.md",[103,112,120,128,136,144],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":107,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":111},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":116,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":111},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":124,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":111},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":132,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":111},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":140,"sourceHtmlUrl":141,"categories":142,"keywords":143,"publishedAt":111},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":148,"sourceHtmlUrl":149,"categories":150,"keywords":151,"publishedAt":111},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]