How It Works

Git tracks what changed. Vreko understands who changed it. And more importantly, why.

The Journey

Timeline	What Vreko Does	You Get
Day 1	Detects AI tools, catches common risks	94% accuracy right out of the box (no tuning needed)
Day 30	Learns YOUR codebase patterns	”Cursor breaks this auth module”
Day 90	Predicts problems proactively	Issues caught before you notice

Detection

Vreko watches every save. Two systems work together:

Automatic Snapshots

Vreko decides when to create snapshots based on context:

Trigger	Action
AI tool makes substantial changes	Snapshot
Critical files modified (auth, config)	Snapshot
Multiple files changed rapidly	Snapshot
High-risk patterns detected	Snapshot

Protected by default: Source code, configs, environment files, documentation.

Not protected: .git/, node_modules/, build outputs, binaries.

Sessions

Vreko groups related changes automatically:

Session: "Claude refactored auth" (14:05 - 14:23)
├── src/auth.ts      (3 snapshots)
├── src/user.ts      (2 snapshots)
├── src/index.ts     (2 snapshots) ← undefined reference!
└── AI Detection: HIGH RISK

Navigate entire sessions with one click. Not file-by-file like Git or Cmd+Z.

Protection Levels

Level	Behavior	Default Files
🟢 Watch	Silent auto-snapshots	Source code, docs
🟡 Warn	Proceed with risk boost	package.json, tsconfig.json
🔴 Block	Hard stop, no write	Lock files, .env*

Timeline vs Git

Aspect	Git	Vreko
Tracks	Commits you make	Every save, automatically
Granularity	Commit-level	Save-level
AI awareness	None	Full attribution
Context	Commit message	Cursor position, AI tool, risk score

Use both: Git for version control. Vreko for understanding AI-assisted development.

Privacy

Stored locally:

• Snapshots and file states
• Pattern learnings and risk scores
• Session metadata

Never collected:

• Source code content
• File diffs
• Proprietary logic

Configuration

Customize with .vrekorc:

{
  "protection": [
    { "pattern": "src/auth/**/*", "level": "block" },
    { "pattern": ".env*", "level": "block" }
  ],
  "ignore": ["*.test.ts"]
}

Next Steps

• Quick Start - Install in 2 minutes
• MCP Integration - AI assistant tools
• CLI Reference - Terminal commands
• Troubleshooting - Common issues