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
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=...
Or have:
package.json
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
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
Then run it inside a repository:
repodrift scan
You can also scan another project:
repodrift scan ./my-project
For development, the same functionality can be run without globally installing the package:
npm run dev -- scan
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
Custom ignore patterns can also be configured with:
.repodriftignore
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
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
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
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
For example:
Repository Health
78 / 100
Grade: B
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
to generate machine-readable output.
This makes it possible to integrate RepoDrift into CI/CD pipelines.
For example:
repodrift scan --json --fail-on high
The idea is simple:
Git Push
↓
CI Pipeline
↓
RepoDrift
↓
Repository Analysis
↓
Critical/High Findings?
↓
Yes → Fail
No → Continue
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
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
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"
}
Instead of sending:
API_KEY=sk_live_123456789
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
So the philosophy is:
Core = Detection
AI = Understanding + Explanation + Recommendations
Future: repodrift explain
One of the planned commands is:
repodrift explain
Instead of simply showing:
HIGH
Vulnerable dependency
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.
Future: repodrift fix
Eventually, I want RepoDrift to go beyond analysis.
A future command could be:
repodrift fix
The workflow could become:
Find Issue
↓
AI Analysis
↓
Generate Patch
↓
Show Diff
↓
Developer Approval
↓
Apply Change
↓
Run Tests
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
For CI:
repodrift scan --json --fail-on high
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
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
Then:
cd your-project
repodrift scan
Or:
npx @repodrift/cli scan
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.
