Overview

Weave is a version-control system built for many people and AI agents editing one codebase at the same time. It tracks code by symbol — a function, method, class, constant or JSON key — not by line. Instead of merging, it keeps everyone in real-time sync and gives every symbol an owner. Clashes never block anyone, and nobody's work is lost.

There are two parts:

New here? Go to the Quickstart. Building with AI agents? Read For AI agents. Agents can fetch these docs as plain text: /docs/llms.txt (an index) or /docs/llms-full.txt (every page in one file). Every page is also available as Markdown at /docs/<page>.md.

How Weave works in one minute#

1. You work in a workstream (main, dev, feature/auth). Everyone on a workstream sees the same head.
2. You edit files on disk as usual. weave add records your edits, by symbol, in your private draft. Nobody sees a draft.
3. weave stitch -i "<intent>" -w "<why>" seals the draft into one stitch with what it is for and why.
4. The server runs the weave check. If it passes, the stitch is weaved: the head moves forward and everyone receives it.
5. If you changed a symbol someone else owns, that part goes to them as a suggestion. The rest weaves at once.
6. If your change clashes with newer work, it also goes to that person as a suggestion. Nothing fails. If they reject it, a resolution point keeps both versions.

weave clone acme/shop && cd shop
weave claim src/cart.ts::addToCart --feature "quantity support"
# ... edit src/cart.ts ...
weave add
weave stitch -i "Add quantity to addToCart" -w "the mobile app sends a quantity"

How Weave differs from git#

Weave is not git with a different name. Git lets everyone change anything on a private copy and reconciles the copies later, line by line. Weave keeps everyone on the same head in real time and decides, per symbol, who changes what.

Coming from git: what to use instead#

Weave can still talk to git when you need it: the server can import a git repository and mirror a workstream to a git remote (see the API reference).

Core concepts#

Symbols#

Weave parses every file into symbols, losslessly. Two people changing different functions in the same file never clash. Parsed languages: Rust, TypeScript/JavaScript (TSX/JSX), Python, Go, Java, C#, Swift, PHP, CSS and SCSS/Sass. A JSON file whose top level is an object is split per key (dependencies.react, scripts.build), so two agents adding different keys to package.json never clash. Other files are one whole-file symbol. Files on disk stay ordinary files, so editors, compilers and builds keep working.

A symbol is named file::qualified::name, for example src/auth.rs::Auth::login or package.json::scripts.dev.

Draft → stitch → weave#

Weaved means deployable for that workstream. Heads only move forward.

Owners, claims and suggestions#

Anyone can change an unclaimed symbol. To own something, claim it: weave claim src/auth.rs::login. A claim lasts for a lease (10 minutes by default) that weave watcher renews. When someone else changes a symbol you own, their change does not overwrite yours: it arrives as a suggestion you accept or reject. Ownership routes work; it never blocks it.

Clashes never block#

• A stale copy (text exactly as Weave last wrote it) loses quietly to the newer head.
• A real edit that clashes with newer work by someone else goes to that person as a suggestion. The rest of your stitch weaves. Both of you get a message.
• If they reject it, a resolution point keeps both versions, side by side, until someone picks one.

Workstreams and the chain#

Workstreams form a chain, for example main ← preprod ← dev. Stitches move up one at a time by promotion and come down by inheritance. When the same symbol changed differently on both sides, Weave opens a change request showing both versions with their intent and why. See Workstreams.

Decisions#

A decision record says why code is the way it is: a title, the why, rejected alternatives and constraints, anchored to symbols. Records travel with the code through drafts, stitches, promotion and inheritance. See Decisions & history.

Agents#

An AI agent is a first-class author. Each agent has its own session (its own draft and active workstream, even in a shared checkout), ideally its own agent token, and optionally a path scope that limits what it may change. See For AI agents.

Glossary#