How VERSY works.

Built for agents. Directed by you.

People, autonomous agents, CI systems, and other tools interact with VERSY as Actors. Each can inspect repository state, declare intended work, record attempts, and hand off the result through a structured interface.

VERSY is a native VCS with its own storage and history model. It stays independent of AI providers and models. You choose the agents and run them with your own tools; VERSY records and coordinates their development work. It does not start or schedule agents.

One objective. Room to experiment.

Change — the objective

A piece of work with a stated intent, such as fixing a parser bug. Competing approaches can belong to the same Change.

Run — an attempt

One attempt starts from an explicit source state. Separate Runs let agents explore alternatives without sharing a mutable directory.

Workspace — the place to work

A managed directory belongs to one Run. Give each filesystem writer its own Workspace so parallel edits remain isolated.

Checkpoint — an exact saved state

An immutable, content-addressed snapshot reconstructs the supported repository state exactly. Explicit parent relationships preserve its place in history.

Two approaches to the same bug.

Imagine asking two agents to fix a parser bug. Both start from the same Checkpoint, in separate Runs and Workspaces. One changes the parser; the other tests a smaller input-handling fix.

Each agent saves its result and records the checks it ran. You can compare the two Candidates and record the reason for choosing one. The other attempt stays in history, including a failed approach that might save the next agent from repeating it.

Illustrative workflow: external actors do the work and make the decision. VERSY retains the records. Updating the repository-root files is a separate synchronization step.

Coordinate before edits collide.

Leases declare which paths a Run is working on. Intent Reservations describe the planned operation and its targets. Overlap inspection gives actors a chance to coordinate before combining their changes.

Advisory overlap is a warning; exclusive Leases block overlapping leases from other Runs. Intent is a declaration, while captured filesystem state is an observation. Separate Workspaces keep the editing isolated; coordination does not make concurrent writes to one directory safe.

Keep checks and reasons close to the code.

Evidence records an actor's report of an external check against an exact Run and Checkpoint, such as a test result. VERSY does not run that test, authenticate the actor, or certify correctness.

Rationale records a concise reason: the constraint that mattered, a rejected alternative, or the lesson from a failed attempt. It is deliberately supplied context, not an inferred explanation. When a reason was not recorded, that gap stays visible.

Make acceptance an explicit decision.

A completed Run can offer its result as a Candidate. Selection records the evaluated Candidates, criteria, and cited Evidence and Rationale, or explicitly records missing inputs. Accepting a Candidate advances canonical main; synchronizing the registered root applies that accepted state to its files.

When results need combining, an Integration Run preserves the source identities and records conflicts and their resolutions. If another Change advances main first, integrate against that exact new state. Parallel attempts remain independent; canonical acceptance is guarded and serial.

Give the next agent a place to start.

An agent can inspect exact source, related Runs, recorded intent, Evidence, and decisions before continuing. History includes accepted, failed, and rejected attempts. Explain and query interfaces distinguish observed facts, declarations, attestations, decisions, derived analysis, and missing information.

The CLI returns structured JSON by default. Both vv and versy expose the same interface. Start by discovering the installed contract, then inspect the repository:

vv load --json
vv capabilities --json
vv working-copy status --json
vv fsck --json

Read the complete agent workflow or explore the CLI reference.

Try it on a small project.

VERSY 0.3.0 is an experimental, local-first preview under Apache-2.0. Review supported platforms and filesystems before installing, and keep independent backups of valuable work. VersyHub is coming soon; remote hosting and shared review are not available in this release.

VERSY stands for Version Every Retry, Screwup, and Yolo.