AVP

Product Introduction

1. Definition: AVP (Agent Versioning Protocol) is an open-source version control system specifically engineered for AI coding agents. It functions as a server-based protocol that manages a linear sequence of code states, replacing traditional Git workflows for automated development.
2. Core Value Proposition: AVP exists to solve the integration bottleneck when multiple AI agents work concurrently on a single codebase. Its core value is ensuring every change is proven on the exact head of main before it lands, guaranteeing a perpetually green main branch, eliminating merge conflicts for agents, and dramatically reducing CI overhead.

Main Features

1. Linear, Server-Managed State Line: AVP maintains a single source of truth via a server that holds a numbered line of positions, each representing a complete, verified code tree. This centralizes state management and enables deterministic ordering of changes, which is critical for concurrent agent operations.
2. Agent-Centric Task Workflow (Open/Write/Land): Agents interact through MCP tools or a REST API. They avp_open a task, work in an isolated worktree, and avp_land with an attached proof. This workflow eliminates the need for manual branch creation, pull requests, and merge conflict resolution in agent-driven development.
3. Automatic Replay and Conflict Resolution: If a second agent lands a task while another is in progress, AVP automatically replays the first agent's changes onto the new head and re-runs the proof. Non-overlapping changes combine; overlapping changes are presented as conflict markers directly to the agent for automated resolution, never requiring human intervention.
4. Git-Backed Mirroring: Every successfully landed AVP position is automatically written to the underlying Git repository as a standard commit, complete with commit message, author, and proof status. This ensures full compatibility with existing GitHub workflows, CI/CD systems, and human review processes.

Problems Solved

1. Pain Point: The inefficiency of traditional Git workflows (branch -> PR -> CI -> merge) for high-velocity AI agents, leading to excessive CI runs, lengthy wait times due to rebasing, frequent broken main branches, and staging deploy thrashing.
2. Target Audience: Development teams and solo builders leveraging multiple AI coding agents (like Claude Code, Cursor AI, GitHub Copilot) simultaneously; engineering managers overseeing AI-augmented development processes; startups and small teams aiming to maximize development speed with AI.
3. Use Cases: Parallel development of independent features by multiple agents; rapid iteration and bug fixing with several agents; maintaining a large monorepo with AI-assisted tooling; running benchmarks or automated refactoring tasks concurrently.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros:
     • Guaranteed Main Branch Integrity: Eliminates "red states" in main by proving every change against the exact current head.
     • Eliminates Agent Merge Conflicts: Resolves concurrent modifications automatically, removing a major human bottleneck.
     • Drastic CI Reduction: Runs full test suites per batch of landings, not per change, slashing CI costs and time (e.g., from 104 to 4 daily runs).
     • Faster Integration Time: Reduces median time from open to main from 19 minutes to under 3 minutes.
     • Seamless Git Compatibility: Mirrors all activity to Git, allowing for a gradual adoption path.
   • Cons:
     • Per-Task Proof Overhead: Each landing requires a proof run (median 15s), which can slow down the last delivery in highly concurrent scenarios, as seen in the 12-agent benchmark.
     • Central Server Dependency: Requires running the avp server, introducing a new infrastructure component compared to decentralized Git.
     • Early-Stage Tooling: As a new, open-source project, it lacks the extensive ecosystem, integrations, and hosted service maturity of Git.

2. Key Alternatives & Differentiation:

   • Standard Git/GitHub: The incumbent workflow. AVP differentiates by replacing the pull request/merge queue model with a linear, proof-first protocol. It automates conflict resolution for agents and batches CI, whereas Git requires manual conflict handling and triggers CI per PR.
   • Jujutsu VCS (jj): A modern, Git-compatible version control system. Benchmark data shows Jujutsu still allowed broken states (red main) and lost tasks. AVP differentiates with its server-centric design for agent coordination and its absolute guarantee of a green main through pre-land proofs.
   • Isolated Worktrees: A common current practice to prevent agent interference. AVP complements this by solving the subsequent integration problem, providing the "how they all come back to main" mechanism that worktrees alone lack.

Frequently Asked Questions (FAQ)

1. How does AVP handle merge conflicts between AI agents? AVP automatically replays an agent's changes on top of the latest landed code. If changes overlap, it generates standard conflict markers (e.g., <<<<<<<) directly in the agent's working files. The agent is then responsible for resolving these conflicts programmatically before attempting to land again, preventing broken code from reaching the main line.

2. Can I use AVP with my existing GitHub Actions and deployment pipelines? Yes. AVP is designed for backward compatibility. Every landed position is committed to your Git repository. Your existing GitHub CI/CD workflows will trigger on these commits as usual. The reduction in CI runs comes from AVP batching multiple logical changes into fewer pushes to the Git remote.

3. Is AVP only for AI coding agents, or can human developers use it? While built for AI agent integration, the avp command-line tool allows human developers to use the same Open/Write/Land workflow. This enables a unified process for both human and AI contributions, though the primary efficiency gains are realized in automated, high-concurrency environments.

4. What programming languages and project types does AVP support? AVP is language-agnostic. The avp up command auto-detects projects in Node.js, Python, Rust, Go, Java, and Ruby to suggest default proof steps (like npm test or pytest). The proof system in avp.toml can be configured to run any shell command, making it compatible with any tech stack.

5. How does AVP's performance and cost compare to using Git with agents? Benchmarks show comparable total runtime and token cost per task batch. The key difference is allocation: AVP spends time on per-task proofs to prevent breakage, while Git spends time on repeated CI runs and manual conflict resolution. AVP reduces overall infrastructure cost (CI minutes) and opportunity cost (developer time spent on broken main branches).