Let's be realistic, every Flutter project accumulates dead weight over time, big images not deleted, a logo variant from a rebrand, a placeholder image a dev forgot to delete.
Individually they're small but they add up to real APK/IPA size.
I built cleanbev to fix that locally, and I now a new upgrade is available a GitHub Action so the check runs automatically on every pull request, instead of running it localy.
What cleanbev actually does
cleanbev is a command-line tool for Dart and Flutter projects. It:
- Reads your
pubspec.yaml to find every declared asset
- Scans your Dart code for references to each one
- Reports anything declared but never referenced
- Optionally deletes what you confirm
Locally, it's interactive:
dart pub global activate cleanbev
dart pub global run cleanbev --assets-path assets/images
✓ Asset assets/images/logo_white_bg.png is not used in the project. Do you want to delete it? · no
Asset assets/images/logo_white_bg.png has not been deleted.
✓ Asset assets/images/download_image-car.jpeg is not used in the project. Do you want to delete it? · yes
Asset assets/images/download_image-car.jpeg has been deleted.
It's also available as an MCP server, so editor-integrated agents (VS Code, Cursor, Visual Studio) can call it directly while you're working.
The gap: someone could forgot to cleanup some assets before pushing
A local CLI tool only helps if someone remembers to run it but in practice, unused-asset cleanup falls into the same bucket as "update the changelog" or "check for outdated dependencies" but under
deadline pressure this could be skipped.
The only way it reliably happens is if CI enforces it.
That's what the new Cleanbev Asset Check action does.
Using it
Add this into any Flutter repo's .github/workflows/:
name: Check Unused Assets
on:
pull_request:
branches: ["main"]
jobs:
cleanbev-asset-check:
name: Cleanbev Asset Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Cleanbev
uses: koukibadr/cleanbev-action@v1
with:
assets-path: "assets"
blocking: "true"
| Input | Description | Default |
|---|
assets-path | Path to the assets directory to scan | assets |
blocking | Fail the job when unused assets are found | false |
Two ways to run it
blocking: "false" (default) — reports what it finds, cleans it up, never fails the build. Good for a low-friction "just keep things tidy" job on a schedule or on pushes to main.blocking: "true" — turns it into a real PR gate. If a PR introduces an asset that's never referenced, the check fails until it's cleaned up or actually used. This is what I run on pull requests.
Try it
It's a small tool solving a small, annoying problem. If you try it on a real project and hit a bug please send me your issues and PRs.