bgbgone.
Showcase
Gallery
How
Install
GitHub
Background,gone.
The UNIX-style background remover for macOS. Apple Vision on-device. No cloud, no API keys, no GUI side-effects.
$ brew install Arthur-Ficial/tap/bgbgoneCopy
Apple Silicon · macOS 26+ · source on GitHub
Show, don't tell
One flag. Sixteen subjects.
Same CLI invocation against sixteen strict-public-domain Wikimedia subjects: photography, painting, spacecraft, woodblock print, vintage product ad. Zero per-image tuning.
$ bgbgone in.jpg > out.png · 16 strict-PD subjects · zero config
Tech note · how the matte is made
Apple's foreground-instance mask, in a UNIX pipe.
The default --algo auto path calls VNGenerateForegroundInstanceMaskRequest — the same foundation-model-class extractor used by the iPhone's lift-subject gesture. bgbgone reads the input via ImageIO, builds a VNImageRequestHandler, and returns the resulting alpha matte. The matte is rendered into an explicit DeviceGray CGImage before CGContext.clip(to:mask:) applies it to the source RGB — this colour-space step is the difference between “background actually removed” and “silently passes through.”
Composite gallery · 53 panels
Anywhere × anything.Each tile is one bgbgone subject.jpg --bg image:scene.jpg -o panel.jpg. Every subject AND every background is documented public-domain: NASA / JPL-Caltech, Wikimedia PD-old, ESA-Hubble, JWST.
Tech note · what the gallery is
Two hundred bytes per panel.
Each tile is a fully composited PNG, then re-encoded to a small AVIF (≈12-30 kB at 480 px wide) with a JPEG fallback. The grid uses loading=“lazy” and decoding=“async” on every image, so only the tiles you scroll past actually leave the CDN. Mobile gets the 480 px variant; ≥1000 px viewports get the 960 px variant. No JavaScript framework; the grid is plain CSS Grid.
Matte controls
Feather, threshold, padding, shadow.
Every knob, on the same studio portrait — feather 0 → 16 px, then crop, padding, shadow and the raw alpha matte (--mask-only). The compositor blends with that matte to produce every other output on this page.
--feather · --crop · --padding · --shadow · --mask-only
Tech note · the feather you nearly couldn't see
Why a Gaussian-blurred mask matters.
In v0.1.16 of bgbgone, --feather > 0 silently disabled background removal — the Gaussian-blurred mask was an sRGB CGImage, and CGContext.clip(to:mask:) only treats grayscale-with-no-alpha inputs as masks, so the clip became a no-op and the original image flowed through unchanged. v0.1.18+ rasterises the blurred mask into an explicit DeviceGray 8-bit context before returning it. The integration suite now asserts that the corner pixel of an EVA cutout has alpha 0 at feather radii 0, 8 and 16 — so the bug can never come back.
--algo
Three algorithms, side by side.
Apple Vision exposes three public segmentation primitives. auto = foreground-instance mask; person = portrait segmenter; saliency = objectness heat map. Unsupported names are rejected at parse with exit code 2 — never silently routed.
--algo vn-mask · person · saliency
How it works
Apple Vision in a UNIX pipe.
Every Mac since macOS 14 ships VNGenerateForegroundInstanceMaskRequest — only callable from Swift. bgbgone is the thin, hard-tested CLI that wraps it.
~/photos
# single cutout to a transparent PNG
$ bgbgone photo.jpg > out.png
# brand background, JPEG, tight crop, soft edge
$ bgbgone selfie.jpg --bg color:#0066cc --crop --feather 2 \
--to jpg --quality 95 -o avatar.jpg
# batch a folder, stream NDJSON for jq
$ ls *.heic | xargs -I{} bgbgone {} --ndjson --out-dir ./out/ \
| jq -s 'group_by(.algo) | map({algo: .[0].algo, n: length})'
# pipe into auge for cleaner downstream classification
$ bgbgone in.jpg --bg color:black --to jpg -o /tmp/c.jpg \
&& auge --classify /tmp/c.jpg --top 3
0
network calls
NetworkGuard registers a URLProtocol that intercepts http / https / ws / wss inside the process and exits with code 3 if anything tries.
75
tests passing
60 unit tests on the pure-Swift core (no XCTest, no Testing framework). 15 integration tests spawning the real binary across all 16 PD fixtures.
86 ms
avg per image
100-image performance harness: 11.6 images/s, 86 ms/image on Apple Silicon. One make perf-100 guards the regression.
Install
One brew tap. Two minutes.
Apple Silicon, macOS 26+. No Xcode required.
Homebrew
brew tap Arthur-Ficial/tap
brew install Arthur-Ficial/tap/bgbgone
bgbgone --version
bgbgone --check
bgbgone photo.jpg > cutout.png
Already installed? brew upgrade bgbgone.
From source
git clone https://github.com/Arthur-Ficial/bgbgone
cd bgbgone
make install
# bumps patch, builds release,
# installs to /usr/local/bin
Regenerate README assets with make readme-images; ship with make release.
Sibling tools
Part of the apfel ecosystem.
On-device CLI tools for Apple frameworks Apple never wrapped. Each one is one binary, one purpose.
Tool Capability Apple framework
apfel LLM (text generation) FoundationModels auge Vision / OCR Vision bgbgone (this)Background removal Vision + Core Image ohr Speech-to-text SpeechAnalyzer kern Embeddings NLContextualEmbedding
© 2026 Arthur-Ficial · GitHub · MIT licence franzai.com
Every image on this page is verifiable public domain — NASA / JPL-Caltech (PD-USGov), the JWST and Hubble image archives (NASA & ESA release for free public use), Wikimedia PD-old reproductions (Hokusai, Vermeer, da Vinci), and pre-1929 American magazine ads (Singer, Underwood, Edison, Pierce-Arrow). Full provenance per fixture in LICENSES.md .
