Bouncer: Teaching a Folder to Reject Bad Files

The idea for Bouncer came from a Friday afternoon of frustration. We had a workflow where files landed in a shared directory — reports, data exports, config files, you name it — and downstream processes assumed those files were clean. Correctly formatted. Complete. Consistent with what came before.

They were not always clean.

The failure mode was always the same: a malformed file would slip through, something downstream would choke on it hours later, and someone would spend their evening tracing backwards to figure out which file was the problem and why nobody caught it.

We'd tried the obvious things. Linting scripts. Validation hooks. Manual spot-checks. Each worked for the specific case it was written for and missed everything else. The problem wasn't any single check — it was that quality is multidimensional, and a file can pass format validation while being completely wrong in ways a regex can't catch.

What If the Folder Had a Bouncer?

That's literally how we framed it. A nightclub has a bouncer at the door. The bouncer doesn't just check one thing — they check your ID, your outfit, whether you're on the list, whether you're too drunk. Multiple checks, applied to every person, before they get through the door.

We wanted that for files.

How It Works

Bouncer uses watchdog to monitor directories. When a file lands, it enters a pipeline of 12 pluggable quality agents. Each agent is a focused check:

• Format Agent — is this actually valid JSON/CSV/YAML/whatever it claims to be?
• Schema Agent — does the structure match what downstream expects?
• Completeness Agent — are required fields present? Any suspicious gaps?
• Consistency Agent — does this conflict with the last N files in the same stream?
• Range Agent — are numeric values within expected bounds?
• Freshness Agent — is the data timestamped recently, or is this a stale re-upload?

Those six are mostly deterministic. The next six are where it gets interesting — they use Claude to evaluate things that rules can't catch:

• Semantic Agent — does the content make sense in context?
• Anomaly Agent — does anything look statistically unusual compared to history?
• Compliance Agent — does this meet domain-specific regulatory requirements?
• Duplicate Agent — is this substantially the same as a file we've already processed?
• PII Agent — is there personally identifiable information that shouldn't be here?
• Summary Agent — generates a human-readable quality report for the file

Each agent returns a pass/fail/warn verdict with an explanation. If an agent can fix the issue (like reformatting a malformed CSV header), it does so automatically and notes the fix.

The Auto-Fix Loop

This was the feature that surprised us the most in terms of impact. About 40% of quality failures we were seeing were trivially fixable — wrong date format, trailing whitespace, BOM characters, inconsistent line endings. The kind of stuff that breaks parsers but doesn't represent an actual data problem.

Bouncer's auto-fix loop handles these transparently:

1. File arrives
2. Quality agents run
3. If failures are auto-fixable, Bouncer applies fixes and re-runs the failing checks
4. If the file passes after fixes, it proceeds with a note about what was changed
5. If it still fails, it's quarantined and notifications go out

The fixed file is always saved alongside the original, so there's no silent mutation. You can diff them if you want to know exactly what changed.

Notifications

Nobody wants to poll a dashboard. Bouncer pushes alerts through whatever channel your team already uses:

• Slack — a message with the file name, which checks failed, and whether auto-fix was attempted
• Email — a digest of quality events, configurable frequency
• Webhooks — POST to your own endpoint for custom integrations

Notifications only fire for failures and warnings. If everything passes, Bouncer stays quiet. We were deliberate about this — alert fatigue kills monitoring systems faster than anything.

The Textual TUI

This is the part we built for ourselves and ended up loving. Bouncer includes a terminal UI built with Textual that shows live monitoring status:

• Files currently being checked
• Recent verdicts (pass/fail/warn) with agent-by-agent breakdown
• Auto-fix activity
• Queue depth if files are arriving faster than checks complete

It's not necessary — Bouncer works fine headless — but when you're debugging a quality issue or watching a batch import, having a live view of what the agents are seeing is invaluable.

Why 12 Agents Instead of 1 Big Prompt?

We tried the monolithic approach first. One big prompt: "Check this file for all quality issues." It kind of worked. But the results were inconsistent — sometimes it'd catch formatting issues and miss semantic problems, other times the reverse.

Splitting into focused agents was the fix. Each agent has a narrow job, a specific prompt tuned for that job, and its own pass/fail threshold. When the Completeness Agent says a file is missing required fields, you know exactly which check caught it and why. When you need to adjust sensitivity for one type of check, you tune one agent without affecting the others.

It also lets you compose pipelines. Not every directory needs all 12 checks. A config file directory might only need Format + Schema + Consistency. A data export directory might need all 12. You configure per-directory.

Try It

Bouncer is open source and we use it daily. If you've got a folder full of files and a team that's been burned by bad data making it downstream, check out the case study or grab it from GitHub.

Fair warning: once you set it up, you'll start wondering how you ever worked without it. That's not marketing — it's what happened to us.