devLap

I Built RepoDrift: A Local-First CLI That Audits Your Repository Before Deployment

typescript dev.to

Most developers focus on whether their application works.

But before deploying a project, there are other questions worth asking:

  • Are there exposed secrets?
  • Are dependencies outdated?
  • Is a lockfile missing?
  • How large has the codebase become?
  • Are there large or suspicious files?
  • Is the Git working tree clean?
  • Are there obvious technical debt signals?
  • Is the repository actually healthy?

I wanted a simple way to answer those questions directly from the terminal.

So I built RepoDrift.

RepoDrift is a local-first repository intelligence CLI for developers.

It analyzes a repository and produces a health report without requiring source code to be uploaded to a cloud service.

What is RepoDrift?

RepoDrift is designed to run directly inside a project:

npx @repodrift/cli scan
Enter fullscreen mode Exit fullscreen mode

It currently analyzes:

  • Files and directories
  • Dependencies
  • Lockfiles
  • Security patterns
  • Git status
  • Code metrics
  • Repository health
  • Actionable findings

The current release is Phase 1 — local repository analysis.

AI-powered explanations and a remote API are planned for a future phase.

Why I built it

A repository can work perfectly and still have problems.

For example, a project might contain:

.env
API_KEY=...
Enter fullscreen mode Exit fullscreen mode

Or have:

package.json
Enter fullscreen mode Exit fullscreen mode

without a lockfile.

Or contain a huge source file that has gradually become difficult to maintain.

Or have several uncommitted changes before a production deployment.

These aren't always visible when you're simply running:

npm run dev
Enter fullscreen mode Exit fullscreen mode

I wanted a single command that could give developers a quick overview.

That's the idea behind RepoDrift.

Quick Start

You can install the CLI globally:

npm install -g @repodrift/cli
Enter fullscreen mode Exit fullscreen mode

Then run it inside a repository:

repodrift scan
Enter fullscreen mode Exit fullscreen mode

You can also scan another project:

repodrift scan ./my-project
Enter fullscreen mode Exit fullscreen mode

For development, the same functionality can be run without globally installing the package:

npm run dev -- scan
Enter fullscreen mode Exit fullscreen mode

What does RepoDrift actually check?

1. File Analysis

RepoDrift scans the repository structure and identifies:

  • Source files
  • Test files
  • Configuration files
  • Documentation
  • Binary files
  • Large files
  • File extensions
  • Directories

It also ignores directories that normally don't need to be analyzed:

node_modules
.git
dist
build
.next
coverage
.cache
Enter fullscreen mode Exit fullscreen mode

Custom ignore patterns can also be configured with:

.repodriftignore
Enter fullscreen mode Exit fullscreen mode

2. Dependency Analysis

RepoDrift looks at the project's dependency configuration.

Currently it supports common Node.js dependency files such as:

package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
Enter fullscreen mode Exit fullscreen mode

It can identify things such as:

  • Dependencies
  • Dev dependencies
  • Missing lockfiles
  • Deprecated package metadata
  • npm security advisories when network auditing is enabled

For example:

repodrift scan
Enter fullscreen mode Exit fullscreen mode

can give you an early warning that the dependency configuration needs attention.

3. Security Scanning

One of the most important parts of RepoDrift is local security analysis.

It looks for patterns that may indicate:

  • API keys
  • Tokens
  • AWS credentials
  • GitHub credentials
  • Private keys
  • Hardcoded passwords
  • Database URLs
  • Environment files

The goal isn't to replace a dedicated security platform.

Instead, RepoDrift provides a fast first layer of repository inspection before development or deployment.

And privacy is a major part of the design.

Local-First by Design

RepoDrift is designed around a simple principle:

Your source code should stay on your machine unless you explicitly choose otherwise.

The current Phase 1 analyzer performs its repository analysis locally.

You can also use:

repodrift scan --local-only
Enter fullscreen mode Exit fullscreen mode

This guarantees that RepoDrift does not make a network request for the scan.

This is especially important when analyzing:

  • Private repositories
  • Client projects
  • Internal applications
  • Proprietary source code

4. Git Analysis

RepoDrift can inspect the local Git repository.

It can provide information such as:

  • Current branch
  • Working tree status
  • Commit count
  • Contributors
  • Recent commits
  • Uncommitted files

Git analysis is optional.

If Git isn't installed or the target isn't a Git repository, RepoDrift gracefully continues with the other analyzers.

5. Code Metrics

RepoDrift also looks at basic repository metrics.

For example:

  • Lines of code
  • Largest source files
  • Source file count
  • Repository size signals

These metrics aren't intended to judge whether your architecture is "good" or "bad."

They're signals.

The idea is to give developers enough information to decide where they should investigate further.

Repository Health Score

One of the things I wanted to avoid was an AI-generated score.

So the health score is currently deterministic.

RepoDrift combines different repository signals into an overall score.

Conceptually:

Security
   +
Dependencies
   +
Code Quality
   +
Complexity
   +
Git Health
   ↓
Repository Health Score
Enter fullscreen mode Exit fullscreen mode

For example:

Repository Health

78 / 100
Grade: B
Enter fullscreen mode Exit fullscreen mode

The score is calculated by the analysis engine rather than by an AI model.

This means the same repository state should produce a predictable result.

JSON Output for CI/CD

RepoDrift isn't only designed for humans.

You can use:

repodrift scan --json
Enter fullscreen mode Exit fullscreen mode

to generate machine-readable output.

This makes it possible to integrate RepoDrift into CI/CD pipelines.

For example:

repodrift scan --json --fail-on high
Enter fullscreen mode Exit fullscreen mode

The idea is simple:

Git Push
   ↓
CI Pipeline
   ↓
RepoDrift
   ↓
Repository Analysis
   ↓
Critical/High Findings?
   ↓
Yes → Fail
No  → Continue
Enter fullscreen mode Exit fullscreen mode

This allows repository health checks to become part of the development workflow.

Architecture

The most important architectural decision was keeping the core analyzer independent from AI.

The current architecture looks like:

Developer
    │
    │ repodrift scan
    ▼
RepoDrift CLI
    │
    ▼
Core Analysis Engine
    │
    ├── File Scanner
    ├── Dependency Analyzer
    ├── Security Scanner
    ├── Git Analyzer
    └── Code Metrics
    │
    ▼
Health Score
    │
    ▼
Terminal / JSON Report
Enter fullscreen mode Exit fullscreen mode

The Core Engine is responsible for finding facts.

AI will be responsible for understanding and explaining those facts later.

Why AI isn't included yet

I deliberately didn't add AI to Phase 1.

It would have been easy to send repository files to an LLM and call the product "AI-powered repository analysis."

But that's not the architecture I want.

Instead, the future architecture will look like:

Local Repository
       ↓
Core Analysis
       ↓
Redacted Findings
       ↓
RepoDrift API
       ↓
AI Provider
       ↓
Summary
Recommendations
Explanations
       ↓
CLI
Enter fullscreen mode Exit fullscreen mode

The AI won't need the entire repository.

It will receive structured and redacted findings.

For example:

{"severity":"critical","category":"security","title":"Potential exposed API credential","file":"src/config.ts"}
Enter fullscreen mode Exit fullscreen mode

Instead of sending:

API_KEY=sk_live_123456789
Enter fullscreen mode Exit fullscreen mode

the sensitive value would be removed or redacted.

What will AI actually do?

The Core Engine can detect:

Potential exposed credential.

But AI can explain:

Why is this dangerous?

What could happen?

What should the developer do next?

For example:

🚨 Critical Security Issue

A potential credential was detected in the repository.

Risk:
The credential may become accessible to anyone
with access to the repository.

Recommended actions:

→ Rotate the credential
→ Remove it from the repository
→ Review Git history
→ Move the secret to a secure environment variable
Enter fullscreen mode Exit fullscreen mode

So the philosophy is:

Core = Detection

AI = Understanding + Explanation + Recommendations
Enter fullscreen mode Exit fullscreen mode

Future: repodrift explain

One of the planned commands is:

repodrift explain
Enter fullscreen mode Exit fullscreen mode

Instead of simply showing:

HIGH
Vulnerable dependency
Enter fullscreen mode Exit fullscreen mode

RepoDrift could provide:

Why does this matter?

This dependency has a known security issue
that could affect production applications.

Recommended action:

Update the dependency to a patched version.
Enter fullscreen mode Exit fullscreen mode

Future: repodrift fix

Eventually, I want RepoDrift to go beyond analysis.

A future command could be:

repodrift fix
Enter fullscreen mode Exit fullscreen mode

The workflow could become:

Find Issue
    ↓
AI Analysis
    ↓
Generate Patch
    ↓
Show Diff
    ↓
Developer Approval
    ↓
Apply Change
    ↓
Run Tests
Enter fullscreen mode Exit fullscreen mode

The important part is that the developer remains in control.

RepoDrift shouldn't silently modify a project.

Docker and CI

RepoDrift is also designed to work in containerized environments.

A repository can be mounted into a container:

docker run --rm \
  -v "$PWD:/repo" \
  -w /repo \
  node:22-bookworm \
  npx --yes @repodrift/cli scan --local-only
Enter fullscreen mode Exit fullscreen mode

For CI:

repodrift scan --json --fail-on high
Enter fullscreen mode Exit fullscreen mode

This makes the CLI suitable for local development as well as automated workflows.

What I learned building it

The biggest lesson so far is that an AI developer tool doesn't need to start with AI.

A reliable developer tool needs a reliable foundation first.

That's why RepoDrift starts with:

Real Repository
      ↓
Deterministic Analysis
      ↓
Structured Findings
      ↓
Actionable Output
Enter fullscreen mode Exit fullscreen mode

Then AI can be added on top.

This makes the system easier to test, easier to debug, and more predictable.

What's next?

RepoDrift is currently in Phase 1.

The roadmap is:

Phase 1 — Local Analysis

  • File scanning
  • Dependency analysis
  • Security patterns
  • Git analysis
  • Code metrics
  • Health score

Phase 2 — Deeper Analysis

  • Expanded code quality checks
  • Complexity analysis
  • Better configuration
  • More CI fixtures
  • More language support

Phase 3 — AI

  • Replaceable AI providers
  • Redacted AI payloads
  • AI explanations
  • AI recommendations

Phase 4 — Cloud

  • API
  • Historical scans
  • Database
  • Dashboard
  • Authentication
  • Repository monitoring

Phase 5 — AI Engineering

  • AI-generated fixes
  • Patch generation
  • Pull request suggestions
  • Automated repository reviews

Try RepoDrift

Install it with:

npm install -g @repodrift/cli
Enter fullscreen mode Exit fullscreen mode

Then:

cd your-project

repodrift scan
Enter fullscreen mode Exit fullscreen mode

Or:

npx @repodrift/cli scan
Enter fullscreen mode Exit fullscreen mode

The project is open source and available on GitHub.

You can also find the package on npm.

Final Thought

RepoDrift started with a simple question:

"Can I know the health of my repository before it becomes a problem?"

The first version doesn't try to replace developers.

It simply gives them better visibility.

And the long-term goal is to turn that visibility into intelligent, actionable assistance.

Detection first. AI second. Automation later.

That's the direction I'm taking with RepoDrift.

Source: dev.to

arrow_back Back to Tutorials