How It Works

Git tracks what changed. Vreko understands who changed it, and why it matters.

What Vreko observes

The daemon watches file activity in the background - no extra commits, and observation runs asynchronously, off the editor’s critical path.

Observation	What it means
File saves	Every change is recorded as a signal, not just the ones you commit
Sessions	Related changes are grouped into a work session and classified as human or ai-assisted from event timing and velocity - Vreko classifies sessions, not individual keystrokes
AI attribution	When a session is AI-assisted, Vreko identifies the active tool (Cursor, GitHub Copilot, Claude Code, Windsurf) and attributes the changes to it

The intelligence it builds

From those observations the daemon derives three signals and writes them to agents.workspace.json (the open workspace.json v0.3 format). Agents that support the standard consume it automatically - no prompting required.

Signal	Question it answers
Fragility	Which files break or get reverted most often? (derived from change count and revert rate)
Co-change	Which files tend to change together, so editing one implies checking another?
AI attribution	Which parts of the codebase are being written by agents vs humans?

Alongside these, the file carries a frameworkManifest and a health block summarizing the workspace’s intelligence state.

How confident the signals are

Fragility and co-change scores are only as good as the observations behind them. The health.intelligenceState field tells you where a workspace is on that curve - it’s derived directly from a confidence score:

State	Confidence	What it means
INSUFFICIENT_DATA	< 0.30	Just initialized. Scores are seed estimates from git history; treat them as rough.
OBSERVING	0.30 – 0.70	Enough sessions to stabilize. Scores are shifting as real signal accumulates.
CONFIDENT	≥ 0.70	Stable. Fragility and co-change reflect how the codebase actually behaves.

Most actively-developed workspaces reach OBSERVING within a few days and CONFIDENT with sustained sessions across the team.

Protection levels

Independently of the intelligence it builds, Vreko assigns each file a protection level that controls what happens on write.

Level	Behavior	Typical files
🟢 Watch	Observe silently and record a restore point	Source code, docs
🟡 Warn	Record, and surface the change as elevated risk	package.json, tsconfig.json
🔴 Block	Refuse the write	Lock files, .env*, secrets

Levels are assigned automatically; override them per-glob in .vrekorc. See Configuration.

Change history

As it observes, Vreko keeps local restore points so a bad change is recoverable - a safety net, not the headline. Restore points live under ~/.vreko/; roll back from the VS Code sidebar or the CLI. This is deliberately a side effect of observation, not the product.

How it compares to Git

Vreko is not a replacement for version control - it’s the behavioral layer git doesn’t have.

	Git	Vreko
Records	Commits you choose to make	Sessions, automatically
Knows about AI	Nothing	Which tool wrote what
Surfaces	What changed	Which files are fragile, which co-change, who changed them

Use both: Git for version control, Vreko for understanding how the code - and the agents touching it - actually behave.

Privacy

Everything Vreko stores (restore points, learnings, agents.workspace.json) lives locally under ~/.vreko/. See Privacy & Data for the full breakdown.

Next Steps

• Quick Start - Install in 2 minutes
• Configuration - .vrekorc, .vrekoignore, protection levels
• MCP Integration - AI assistant tools
• Troubleshooting - Common issues