The story behind CleanDrop: a local-first Chrome extension that gives downloads better names and schedules their cleanup without blindly trusting a file path.
You know the routine. You download a PDF and Chrome saves it as download (7).pdf. You tell yourself you'll rename it later. A week passes. Now you have six files with names that tell you absolutely nothing.
And then there's the other problem: the Downloads folder slowly becomes a storage unit for things you needed once. A presentation for a meeting that ended last week. A ZIP you extracted months ago. A screenshot you only needed long enough to send it to someone.
I wanted two small conveniences: make downloads easier to recognise, and let me say, “I only need this for a day, clean it up later.” That sounded like a small browser extension.
The first idea was simple. The safe version wasn't. Renaming a file is easy; trusting a cleanup operation that will run tomorrow is a different problem.
That project became CleanDrop.
CleanDrop's popup: a simple queue for downloads I've explicitly chosen to clean up.
There was one question I hadn't thought through at first: what if the file disappears, and a completely different file takes its place at exactly the same path? Should the scheduler delete it just because the timer expired? Obviously not. That question ended up shaping the most important part of the design.
1. Make filenames useful before reaching for AI
My first instinct was to send every generic filename to a model. But why call one for a file already named Quarterly_Financial_Report.pdf?
CleanDrop tries the available evidence in order:
- Keep the original name if it is already meaningful.
- Inspect the URL for a useful filename, such as
/files/annual-report-2025.pdf. - Use context from the page that initiated the download if the URL is opaque.
- Only if those steps produce no suggestion, ask the optional local model.
The analyzer flags generic names (download, document), camera/screenshot patterns, numeric basenames, UUIDs, hashes and known CDN rewrites.
The page and the file may come from different places
A download button can live on a documentation site while the file itself comes from a CDN. Looking only at the download URL can miss the useful clue: the page the user was reading.
A content script captures the page URL, title, description and Open Graph metadata; it does not scrape the body. The service worker keeps recent contexts in memory, matching the exact referrer, then its origin, then the download origin. If a restart clears that context, it falls back to the active tab.
Only a no_suggestion result reaches the local model. Its request includes the original filename, URL, referrer and page metadata. The prompt restricts it to that evidence, asks it to preserve the extension and forbids inventing file contents.
For example, this is the kind of context it may receive:
{
"filename": "IMG_20260828.jpg",
"url": "https://example-garden-blog.com/tulips.jpg",
"page_title": "10 Best Spring Flowers For Your Garden",
"page_description": "A guide to planting tulips, daffodils, and crocuses."
}
The model endpoint is OpenAI-compatible and runs on 127.0.0.1. The Python request has a six-second timeout; the extension has an eight-second outer timeout guard. If the model is unavailable, slow or returns unusable output, Chrome keeps the original filename. A failed rename should never become a failed download.
The principle is simple: use evidence that's already there; let the model handle only the ambiguous remainder.
The extension uses Chrome's onDeterminingFilename event, which supports asynchronous filename suggestions when the listener returns true and calls suggest later. Chrome's downloads API documents the event contract.
2. The browser process couldn't be my scheduler
The next problem was less visible but had a big impact on the architecture.
CleanDrop communicates with its Windows companion through chrome.runtime.sendNativeMessage(). With this API, Chrome launches the native messaging host for an individual message. That is useful for short request/response work, but it is not a process you should expect to sit around checking a database every few seconds.
So I separated two jobs that have different lifetimes:
-
cleandrop-host.exehandles browser requests: suggest a filename, schedule cleanup, cancel an item or list pending items. -
cleandrop-scheduler.exeruns continuously after user logon. It checks for expired downloads every 30 seconds and runs the local-model watchdog every 15 seconds.
The extension owns browser interaction. The host answers the browser. The scheduler owns work that must continue after the browser request ends.
Two companion processes, because a browser request and a background scheduler should not have the same lifecycle.
This distinction follows Chrome's native messaging model: sendNativeMessage starts a host for a message, while connectNative provides a longer-lived port. Chrome's native messaging documentation explains the difference.
3. A path isn't a file identity
Back to that question from the beginning.
Imagine CleanDrop schedules this file for tomorrow:
C:\Users\me\Downloads\invoice.pdf
Before tomorrow, the original file is removed. Another file is later placed at exactly the same path. A naive scheduler sees invoice.pdf, sees that it is due, and deletes it.
But that is not the file the user scheduled.
A path tells you where to look. It doesn't prove what is currently there.
On Windows, CleanDrop calls GetFileInformationByHandleEx with FileIdInfo. The returned FILE_ID_INFO contains a volume serial number and a 128-bit file ID. When the user schedules cleanup, CleanDrop stores those values alongside the path and expiry timestamp.
When the file becomes due, the scheduler:
- Claims the scheduled database row.
- Checks that the stored path exists.
- Reads the current file identity at that path.
- Compares it with the identity captured when cleanup was scheduled.
- Proceeds only if the identities match.
The important check is small:
actual_identity = get_file_identity(path)["identity_key"]
if actual_identity != download["identity_key"]:
return {"status": "IDENTITY_MISMATCH", "path": str(path)}
If the file is missing, the operation returns NOT_FOUND. If a different file occupies the path, it returns IDENTITY_MISMATCH. If the identity matches, CleanDrop asks the Windows Shell to move the file to the Recycle Bin using FOF_ALLOWUNDO, then checks that the original path is gone.
Identity is checked before the Recycle Bin operation. It is a safety gate, not an atomic filesystem transaction.
What if the user clicks Keep at the same time?
There's another race: the scheduler notices that a file is due just as the user clicks Keep file.
CleanDrop handles this with conditional SQLite updates. The scheduler can change a row from SCHEDULED to DELETING only if it is still scheduled and due. The keep action can change it from SCHEDULED to CANCELLED only if it is still scheduled. Whichever update commits first wins; the other operation no longer matches its expected state.
The scheduler's claim is a conditional update:
UPDATE downloads
SET delete_status = 'DELETING'
WHERE id = ?
AND delete_status = 'SCHEDULED'
AND delete_after IS NOT NULL
AND datetime(delete_after) <= datetime('now');
This isn't a distributed lock. It's a small compare-and-set style transition for two competing operations on one local database row. That's the mechanism this design needs.
There are still limits. CleanDrop checks identity at the stored current_path; it doesn't search the drive to rediscover a file after it has been moved. And identity verification happens before a separate path-based Recycle Bin call, leaving a check-then-act window. The current implementation narrows the risk; it doesn't eliminate it.
Windows documents the volume serial number and 128-bit file ID in FILE_ID_INFO.
4. The performance surprise was in SQLite
CleanDrop stores only downloads the user has explicitly scheduled for cleanup. During a Windows benchmark, mean SQLite insert latency was 45.01 ms with the rollback journal.
I switched the connection to Write-Ahead Logging and synchronous=NORMAL:
connection.execute("PRAGMA journal_mode=WAL")
connection.execute("PRAGMA synchronous=NORMAL")
In that recorded test, mean insert latency fell to 3.07 ms about 14.7× faster. The p99 moved from 213.82 ms to 14.42 ms.
Measurements from the recorded Windows / Python 3.12.4 test environment, not a guarantee for every machine.
WAL changes SQLite's read/write behavior and can help readers and writers make progress concurrently. It also introduces checkpointing considerations. synchronous=NORMAL is a trade-off: the database remains consistent, but the most recent committed transaction can be lost after power loss or an operating-system crash. SQLite's WAL documentation and synchronous pragma reference explain the details.
Two other measurements helped shape the design: the native-host round trip averaged 95.07 ms, including subprocess startup, protocol handling and the database operation. That is not a full Chrome end-to-end measurement. The local filename-model benchmark recorded a 1,075.6 ms median and 1,935.3 ms p95, which reinforced why model inference should stay optional and bounded.
5. Let an assistant inspect the queue but don't give it a delete button
I added an optional MCP server so an assistant can answer questions such as “What's scheduled to be cleaned up this week?” or “Keep this file.” Its tools are deliberately limited:
list_scheduled_deletionssearch_downloadsget_downloadkeep_file
There is no delete tool. Reads use SQLite's read-only mode (mode=ro). The only state-changing operation is keep_file, and it can cancel an item only while its status is still SCHEDULED.
The MCP layer excludes incognito downloads, reduces source URLs to hostnames, strips control/invisible characters from website-controlled text and bounds result sizes. These steps reduce exposure; they do not eliminate privacy or prompt-injection risks. The server runs locally over stdio, but connecting it to a cloud assistant still sends tool results into that assistant's conversation. Local transport does not automatically mean local inference.
What I learned and what I'd improve next
CleanDrop started as a convenience feature. It became a project about making automation safe when the world changes between scheduling and execution.
The lessons I’m taking forward are straightforward:
- Use deterministic evidence before paying the cost or accepting the uncertainty of inference.
- Give short-lived browser requests and persistent background work separate process lifetimes.
- Treat paths as references, not identities.
- Make competing state transitions explicit.
- Benchmark before assuming the database is fast enough.
I'd still like to improve moved-file recovery and close the gap between identity verification and the later Recycle Bin operation. CleanDrop is Windows-focused today because it relies on Windows file identity and the Windows Shell.
The bigger lesson is this: automation is easy when everything goes right. Building automation that behaves safely when things change unexpectedly is the hard part.
The source is available at github. If you were building a cleanup tool, how would you handle a file that moves after it has been scheduled?
If you found CleanDrop useful or interesting, consider giving the repo a ⭐ on GitHub. It helps support the project and motivates me to keep improving it!





Top comments (0)