Name: offline-bg-removal
Author: ahkamboh

Set it up with your AI agent

Paste this into Cursor, Claude Code, or Codex.

One-line pitch: offline background removal on your machine. First run downloads BiRefNet general. After that you cut locally.

# paste into your agent

You are helping me set up offline-bg-removal, a local BiRefNet-general background remover (https://github.com/ahkamboh/offline-bg-removal). It is offline background removal on my machine. No API. Photos are not uploaded. Set it up: 1. clone + build (one time): git clone https://github.com/ahkamboh/offline-bg-removal cd offline-bg-removal && pnpm install && pnpm -r build 2. first cut downloads BiRefNet general (~928 MB) to ~/.offline-bg-removal/models/birefnet_general.onnx node packages/cli/dist/cli.js cut photo.jpg 3. optional local UI (drop an image on localhost): pnpm --filter @offline-bg-removal/web dev 4. verify: open the PNG. Subject stays, background is transparent. If a step needs my input (pnpm vs npm, or I already have the onnx), ask me first. You can pass --model /path/to/birefnet_general.onnx or set OFFLINE_BG_REMOVAL_MODEL.

Why

No Remove.bg. No upload.

Hosted cutout tools take the file. offline-bg-removal is a rembg alternative that stays on disk: local-bg-removal, self-hosted-cutout, on-device-bg-removal, no-api-cutout.

cloud · paid API

Remove.bg, Photoroom

You send the photo. They keep a copy. Metered.

python · many models

rembg

Fine tool. This repo is the thinner path: one model, one cache dir, CLI plus a localhost UI.

weights · non-commercial

RMBG-2.0

Looks strong. License is CC BY-NC. We ship BiRefNet general instead.

local · MIT

offline-bg-removal

birefnet-cutout on your machine. Open-background-remover. You keep the pixels.

How it works

Download the model once. Then cut.

onnx-cutout with BiRefNet general. First run writes ~/.offline-bg-removal/models/birefnet_general.onnx (~928 MB). That file is not in git and not in the browser.

01

Install

Clone the repo. pnpm install && pnpm -r build. Bin names: offline-bg-removal and obgr.

02

Cache

Missing weights download once to ~/.offline-bg-removal/models/. Or pass --model / OFFLINE_BG_REMOVAL_MODEL.

03

Cut

offline-bg-removal cut photo.jpg writes a PNG with alpha. Local web UI can drop a file on localhost.

~/.offline-bg-removal

Privacy

The photo does not leave the machine.

No upload

CLI and the local UI read a file on disk. There is no remote cutout endpoint. This GitHub Pages site is marketing and install copy only.

No account

No telemetry, no login, no cloud folder. on-device-cutout means the ONNX session runs where you installed it.

Weights stay home

The 928 MB BiRefNet file lives under your home directory. It is gitignored. Do not commit it. Do not put it in the Pages folder.

Packages

Four folders. One job.

Package	Purpose
packages/core	ONNX runner. BiRefNet general only. ensureModel + removeBackground.
packages/cli	offline-bg-removal / obgr. Commands: cut, serve, demo.
apps/web	Local drop-image UI on localhost. Not this Pages site.
site/	This landing page. Publish the folder as GitHub Pages.

Quick start

Build once. Cut locally.

After the first download, local-background-removal is just a command. photo-cutout-local, birefnet-bg-removal, rembg-local: same binary.

# clone + build

$ git clone https://github.com/ahkamboh/offline-bg-removal

$ cd offline-bg-removal && pnpm install && pnpm -r build

# cut (downloads the onnx on first run)

$ node packages/cli/dist/cli.js cut photo.jpg

$ node packages/cli/dist/cli.js cut photo.jpg out.png

# already have the 928 MB file

$ node packages/cli/dist/cli.js cut photo.jpg --model ~/models/birefnet_general.onnx

# local UI

$ pnpm --filter @offline-bg-removal/web dev

Offline background removal on your machine