DEV Community

Cover image for I built a local CLI to catch architectural drift in the age of AI coding
Shaunak Mukherjee
Shaunak Mukherjee

Posted on

I built a local CLI to catch architectural drift in the age of AI coding

#ai #opensource #productivity #python

Had a problem. Built something to solve it.

If you’re using Cursor, Copilot, or Claude to build applications right now, you know that developer velocity has hit warp speed. You can prompt an AI agent to build a multi-file feature, refactor a module, or generate a complex validation schema in under thirty seconds.

But this velocity comes with a massive, silent tax: accelerated architectural drift and context collapse.

AI assistants excel at micro-level feature generation, but they often struggle with macro-level system consistency. They don't mind deeply nested conditionals, they create circular validation dependencies without blinking, and they generate files faster than human teams can comfortably track. But what happens when a new guy comes in the team?

Before you know it, your repository has highly volatile "hot spots" that are scaling in complexity completely outside your review cycle.

To solve this for the codebases I manage, I built repo-drift — a zero-config, 100% local, read-only Python CLI tool that isolates your biggest technical debt hot spots in seconds.

⚙️ How it works under the hood

repo-drift operates entirely in your workspace terminal. It doesn't sync your code to a cloud database, it doesn't leak your data to an external API, and it takes less than a second to parse thousands of files.

It maps repository health across three primary operational layers:

  1. Git Churn Filtering: It scans your local .git logs over a customizable time window (e.g., 90 days) to track edit frequencies per file, automatically ignoring noise parameters like lockfiles, build folders, and assets.
  2. Structural Complexity Profiling: It targets your high-churn files and parses their absolute Lines of Code (LOC) alongside their maximum nesting indentation depth (a lightweight, hyper-fast proxy for cyclomatic complexity) to generate a weighted Volatility Score.
  3. Knowledge Ownership Mapping: It analyzes historical line-by-line authorship on those high-volatility files to calculate exact contributor code percentages, instantly identifying the implicit human "Context Owners" of your project's riskiest zones.

📈 Benchmarking on a Production Monolith: Dub.co

I didn't want to just test this on simple boilerplate repositories. I pointed the repo-drift V1 engine at the massive, open-source production monolith built by the Dub team.

Here is what the local execution loop looked like:

Terminal output of repo-drift CLI executing against the dub repository, identifying top codebase hot spots inside the partner and program modules in 0.7 seconds.
Terminal output of repo-drift CLI executing against the dub repository, identifying top codebase hot spots inside the partner and program modules in 0.7 seconds.

Generated REPO_DRIFT_INSIGHTS.md markdown file inside VS Code showing a structural breakdown of the high-risk repository paths.
Generated REPO_DRIFT_INSIGHTS.md markdown file inside VS Code showing a structural breakdown of the high-risk repository paths.

The Output Summary

More importantly, look at the architectural story the metrics immediately tell. Over the last 90 days, the Dub repo has seen intense feature iterations around their /partners and /program architecture. Because schemas/partners.ts and types.ts sit right at the top of the volatility index, it warns the engineering lead that core data validation contracts are mutating simultaneously with UI modifications—the exact landscape where fast-moving AI code insertions introduce breaking structural regressions.

Alongside this stdout summary, it generates a full, rich text REPO_DRIFT_INSIGHTS.md report directly inside the scanned directory, detailing explicit complexity breakdowns and author ownership percentages.

🛠️ Spin it against your own codebase

repo-drift v1 is completely open source and written natively in Python. If you want to check your own repository's blind spots over the weekend, you can spin it up in two minutes:

  1. Clone the repository: 
git clone https://github.com/shaunakmukherjee/repo-drift.git
cd repo-drift
Enter fullscreen mode Exit fullscreen mode
  1. Install dependencies and run: 
pip install -r requirements.txt
python main.py --repo 'path/to/your/repository' --days 90
Enter fullscreen mode Exit fullscreen mode

Check it out on GitHub, and drop a star if you find it useful:
👉 GitHub: shaunakmukherjee/repo-drift

I’d love to hear from other developers and engineering leads: What are your primary strategies for tracking code health when feature scaling goes on autopilot? Drop your thoughts or run results in the comments below!

Top comments (0)