remove-bg — usuwanie tła ze zdjęć z CLI, na macOS

remove-bg: usuwanie tła ze zdjęć z natywnego macOS, z poziomu terminala

TL;DR

remove-bg to dwucyfrowa liczba linii Swifta, która opakowuje natywny macOS Vision request VNGenerateForegroundInstanceMaskRequest w CLI. Czyli ten sam silnik usuwania tła co Preview/Finder „Usuń tło” — tylko z terminala, w pipeline’ach, w pętli for po folderze. Plus skill do Claude Code, żeby agent sam to wołał, kiedy mówisz „wytnij tło z tego pliku”.

Repo: github.com/stroniarz/remove-bg Licencja: MIT Wymagania: macOS 14+

Problem

Zdjęcia produktowe, mockupy, hero illustrations, ikonki na Slacka — co kilka dni potrzebuję wyciąć obiekt z tła. Klikanie w Preview działa, ale:

nie działa w pętli po folderze
nie działa z poziomu skryptu publikacyjnego
nie działa, kiedy Claude Code prowadzi cały workflow przygotowania assetów

remove.bg API kosztuje, ma rate limit i wysyła wszystko na zewnątrz. Lokalnych modeli (rembg, BiRefNet) używałem — i jakość bywa, ale instalacja Pythona z odpowiednimi wagami za każdym razem to nie jest „one-liner”.

A Apple od macOS 14 ma w systemie model, który robi to lepiej niż większość lokalnych torchowych setupów. Ten sam, który widzisz w Preview, w Finderze, w Photos. Brakowało tylko CLI.

Rozwiązanie: 70 linii Swifta

let request = VNGenerateForegroundInstanceMaskRequest() let handler = VNImageRequestHandler(ciImage: ciImage, options: [:]) try handler.perform([request])

To są trzy kluczowe linie. Reszta to wczytanie obrazka, kompozycja maski na alfę, zapis PNG. Cały skrypt buduje się jednym xcrun swiftc -O remove_bg.swift -o remove-bg — bez zewnętrznych zależności, bez pip install, bez kontenerów.

Użycie:

remove-bg input.jpg output.png

Batch:

mkdir -p out for f in *.jpg; do remove-bg "$f" "out/${f%.jpg}.png"; done

I to jest cała powierzchnia narzędzia. Bo tak naprawdę inteligencja siedzi w Vision frameworku — i Apple ją utrzymuje.

Dlaczego CLI to było warte zachodu

Trzy momenty z ostatniego tygodnia, kiedy remove-bg ratował robotę:

1. Przygotowanie zdjęć produktowych dla klienta. Folder z 40 fotkami ze studia, każda z bałaganem na podłodze, wszystkie potrzebne na białym/transparentnym tle. Zamiast 40 razy klikać w Preview — for f in *.jpg; do remove-bg "$f" "out/${f%.jpg}.png"; done. Cztery sekundy.

2. Hero ilustracja na bloga. Generuję background w heroes/, do tego potrzebuję mockupa terminala wyciętego na alfę. Skript generate-hero.js woła remove-bg w jednym kroku pipeline’u — bez ręcznego rozdzielania faz „wygeneruj background”, „wytnij obiekt”, „połącz”.

3. Claude Code workflow. „Zrób mi hero do posta o NotebookLM” — Claude generuje grafikę, woła remove-bg, wkleja w hero template, daje preview. Zero klikania.

Punkt 3 był punktem zapalnym do napisania skilla do Claude Code.

Skill do Claude Code

W repo jest plik SKILL.md — frontmatter + opis, który Claude Code czyta i decyduje, czy odpalić to narzędzie. Triggery są dwujęzyczne (EN/PL):

Triggers on phrases like “remove background”, “cut out subject”, “isolate product”, “transparent PNG”, and Polish equivalents (“wytnij tło”, “usuń tło”).

Po ./install.sh skill jest symlinkowany do ~/.claude/skills/remove-bg/. W sesji Claude Code wystarczy:

Wytnij tło z ~/Desktop/produkt.jpg.

Claude czyta SKILL.md, wie że ma uruchomić remove-bg input output, robi to, raportuje ścieżkę pliku wynikowego. Bez tłumaczenia za każdym razem „a teraz uruchom to narzędzie z tymi argumentami”.

To jest dla mnie ten moment, kiedy „tool” staje się częścią agenta, a nie kolejnym CLI do zapamiętania.

Co działa, co nie

Działa: – JPG, PNG, HEIC, TIFF, WEBP — wszystko, co Cocoa potrafi zdekodować – Subject z wyraźną krawędzią — produkty, ludzie, zwierzęta, większość obiektów – Batch po folderze – Pipeline’y CI/CD na macOS runnerach

Nie działa albo działa źle: – macOS < 14 — Vision request nie istnieje, exit 3 – Brak wyraźnego foreground subject — pusta maska, output transparentny – Wiele subjectów na jednym zdjęciu — Vision łączy wszystkie w jedną maskę, nie dokładnie izoluje pojedyncze – Bardzo duże obrazy (>50 MP) — Vision potrafi wyrzucić out-of-memory; trzeba downscale’ować przez sips najpierw

Dlaczego nie po prostu „uruchom Preview z Automatorem”

Próbowałem. Automator workflow z Preview działa, ale: – nie integruje się z Claude Code – wolniejszy (uruchamia GUI Preview) – nie jest pipe-friendly — output to plik w Trashu po Quick Action – nie ma kodów wyjścia do skryptów

CLI z exit codes (0 ok / 1 usage / 2 load failed / 3 Vision error) to standard, który skrypty mogą obsłużyć. Plus 70 linii Swifta jest bardzo przejrzyste — całe repo można przeczytać w 2 minuty.

Plan na dalej

Wersja z prompt-em (jak Claude Vision API) — żeby móc napisać „wytnij tylko buty, zostaw resztę”. Vision tego natywnie nie ma; trzeba by zhybrydyzować z Apple Intelligence albo zewnętrznym modelem.
Dodanie tła — drugi tryb: zamiast usuwać, generować podmiankę tła z prompt-a (Vision + Image Playground od macOS 15).
Web wrapper — rzecz jasna nie publiczny, bo wtedy ktoś by go zaczął rate-limit’ować w produkcji; ale wewnętrzny do paneli klienckich, gdzie obrazy lecą po SSH na MacMini, są przerabiane i wracają na S3.

Repo

Całość na MIT: github.com/stroniarz/remove-bg. Issues mile widziane, PR-y też. Jeśli coś nie zadziała na Twoim macOS — interesuje mnie, dlaczego, bo właśnie po to to publikuję.