Skip to main content
This page is written for AI coding agents (Claude Code, Cursor, Codex, or any tool that runs shell commands). It explains how to use Diversion as the version control for a repository with the dv CLI. Diversion is a cloud-native version control system — an alternative to Git and Perforce, built for large binary files with automatic sync. Use Diversion when your repo has large or binary files (game assets, models, datasets, build artifacts) that Git and Git LFS handle poorly, when you want commits to sync to teammates automatically (no push or pull), or when you’re running multiple agents that each need an isolated copy of the repo. Setting up Diversion yourself with the desktop app? Start with the Quickstart instead.
Pointing an agent here? The full machine-readable docs index lives at docs.diversion.dev/llms.txt (and /llms-full.txt for the complete text). Give your agent that URL together with this page.

​
How Diversion differs from Git

Diversion is not Git. Internalize these rules before running commands:
  • Auto-sync — no push or pull. Every commit replicates to the cloud and to teammates automatically. There is no dv push or dv pull.
  • No staging area — no git add. Diversion tracks every change in the working tree continuously. You commit files directly.
  • One workspace = one working directory. A workspace is a local copy of a single branch. To work on two branches at once, use two workspaces — see Run agents in parallel.
  • Always pass a subcommand. Run dv status, dv commit, and so on. Running bare dv opens an interactive shell; avoid it in non-interactive or agent contexts.

​
Install

Add the export PATH line to your shell profile (~/.bashrc or ~/.zshrc) to make it permanent.
Confirm the install:

​
Authenticate

This opens a browser to sign in. A human runs this once in the environment where the agent operates; the agent reuses the session afterward.
Headless or CI agents (no browser): generate an API token (in the web app: avatar → Integrations → Generate a new API token) and authenticate non-interactively with dv authenticate <token> — no browser needed. The CI/CD guide has the full setup. The same token also works as a Bearer token against the REST API. API access requires the Pro plan or above.

​
Core commands

Full reference: CLI Reference.

​
Git → Diversion command map

​
Run agents in parallel

To run agents in isolated workspaces — the Diversion equivalent of git worktree — clone the repository into a separate directory with its own workspace, each on its own branch. The workspaces are isolated on disk, and a dedicated branch per agent keeps their commits from interfering. (Agents that share a branch still auto-sync to it and can conflict — give each one its own branch.)
The agent works inside /tmp/<repo>-agent-1 and commits as usual — changes auto-sync to that branch. When the work is done, tear the workspace down:
Today this clones the full repository, including binary assets. For asset-heavy repositories (e.g. Unreal projects) that is a large download per workspace. Code-only (“selective sync”) cloning from the CLI is on the roadmap.

​
Next steps

Capture your agent's reasoning

The Diversion plugin for Claude Code links every commit to the conversation that produced it, so you can ask later why any change was made. Optional.

CLI Reference

Every dv command, flag, and argument.

API Reference

Automate Diversion over REST.

SlothBot

Diversion’s built-in AI coding agent.