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

curl -sL https://get.diversion.dev/unix | bash ; export PATH="$HOME/.diversion/bin:$PATH"
Add the export PATH line to your shell profile (~/.bashrc or ~/.zshrc) to make it permanent.
Confirm the install: 
dv version

​
Authenticate

dv login
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

# Start tracking a new project in the current directory
dv init

# Get a working copy of an existing repository
dv clone <repo> [path]

# See what changed in the working tree
dv status

# Commit all current changes (replicates automatically — no push needed)
dv commit -a -m "your message"

# Create a new branch and switch to it
dv branch -c <branch-name>

# Switch to an existing branch, commit, or tag
dv checkout <ref>

# Merge another branch into the current one
dv merge <branch>

# View history
dv log
Full reference: CLI Reference.

​
Git → Diversion command map

GitDiversion (dv)
git clone <url>dv clone <repo> [path]
git initdv init
git add <files>(not needed — changes are tracked automatically)
git statusdv status
git commit -am "msg"dv commit -a -m "msg"
git push / git pull(not needed — auto-sync)
git checkout -b <name>dv branch -c <name>
git switch <name>dv checkout <name>
git merge <name>dv merge <name>
git logdv log
git worktree add <path> <branch>dv clone <repo> <path> --new-workspace --ref <branch>

​
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.) 
# Create an isolated workspace on a dedicated branch
dv clone <repo> /tmp/<repo>-agent-1 --new-workspace --ref <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: 
dv workspace            # list workspaces to find the one to remove (id starts with dv.ws.)
dv unregister -f        # run from inside /tmp/<repo>-agent-1 — detaches the local copy
dv workspace delete <workspace-id> -f
rm -rf /tmp/<repo>-agent-1
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.