Agentic UI Reviewer

An autonomous CLI agent powered by Gemini that audits local frontend code before commits, providing instant architectural feedback and UI optimizations.

Comment

Inspiration

Frontend code review usually pulls in two directions. Stakeholders want a quick sense of whether the UI is healthy and accessible, without digging through component code. Engineers want something they can actually act on — concrete fixes, not vague notes about "improving consistency." And when reviews happen under deadline pressure, the things that get missed are often the quiet ones: a missing ARIA landmark, a component pattern that's technically fine but will cause pain later. We built Agentic UI Reviewer because we wanted something that catches those gaps automatically — a CLI tool, powered by Google Gemini, that behaves like a design-systems architect and accessibility reviewer sitting right in your terminal.

What It Does

Point it at a codebase and it audits the frontend files it finds — .tsx, .jsx, .html, and the rest — for UI quality, structure, and accessibility. It walks the project recursively, skips the build artifacts and generated folders, and sends the actual components to Gemini for review. Everything comes back as one file, UI_Audit_Report.md, and every file it reviews gets two takes on it: a plain-language executive summary describing UI readiness and accessibility impact, and a technical section underneath it with real findings — flagged any types, structural issues — and refactor snippets an engineer can actually use.

How We Built It

It's a TypeScript and Node.js project, built on the @google/genai SDK, and it runs off a single command: npx tsx index.ts .. Under the hood, a recursive scanner walks the directory tree, skipping things like node_modules and .git, and it caps out any file over 100 KB so we're not burning API tokens reviewing a minified bundle. Rather than reviewing files one at a time — which gets painfully slow as a project grows — we batch them and run each batch concurrently, so total runtime tracks closer to the slowest file in a batch than the sum of every file in the project. The last piece is the prompt itself: the system instructions are strict enough that Gemini reliably returns the same two-part Markdown structure every time, with none of the conversational filler models tend to add on their own.

Challenges

Getting Gemini to stick to the format was harder than expected — left to its own devices, it wants to greet you and sign off, and we had to write explicit constraints into the prompt to stop that. Concurrency was its own balancing act: push it too high and you start hitting rate limits, keep it too low and large codebases take forever, so we exposed it as a --concurrency flag and let that be tunable rather than guessing at the right number ourselves. And honestly, getting one prompt to reason well about semantic HTML, JSX component structure, and TypeScript strictness all at once took a lot more iteration than we expected going in.

Accomplishments We're Proud Of

The thing we're happiest with is how well it holds up when something goes wrong. If a single file is too large or the API throws an error, that failure gets caught, flagged in the report, and the rest of the batch just keeps going — nothing stalls the whole run. We also put real effort into making it feel like an actual CLI tool rather than a script: live progress output as files complete, a --help flag that responds instantly because we don't spin up the API client until it's actually needed, and options for ignoring paths or naming the output yourself. And we're proud that one pipeline manages to say something useful to both a designer and an engineer without either of them having to skip past content meant for the other.

What We Learned

Mostly, that agentic CLI tools live or die on predictability. If it hangs without feedback or fails silently, people stop trusting it — the progress indicators and graceful fallbacks aren't polish, they're what make it usable. We also learned a lot about how batching interacts with async I/O and API rate limits in practice, and got a lot better at writing prompts that push a model to behave like a strict linter instead of a conversational assistant.

What's Next

The next big piece is CI integration — running this automatically on pull requests and posting the summary as a comment, with quality gates tied to UI readiness scores. We'd also like to feed Gemini actual rendered screenshots alongside the source code, so it can catch visual and CSS regressions that don't show up in the code itself. And eventually, an interactive --fix flag that takes the suggested refactors and applies them directly to your files.

Built With

Share this project:

Updates

Submission history