# Overview

> What Weave is, how it differs from git, and the core concepts — workstream, draft, stitch, weave, owner, suggestion — with a glossary.
>
> Source: https://www.weave.directory/docs

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:

| Part | Address | What it does |
| --- | --- | --- |
| The platform | `https://weave.directory` | Accounts, organizations, repositories, people, tokens, agents, webhooks and the web UI. |
| The Weave server | `https://api.weave.directory` | Workstreams, heads, the weave check, ownership, suggestions, change requests, resolution points, messages, search and the operation log. |
| The CLI | `weave` (and `weave-watcher`) | Runs on your machine or in an agent's sandbox. Install it with `curl -fsSL https://weave-cli.com/install.sh \| sh`. |

New here? Go to the [Quickstart](https://www.weave.directory/docs/quickstart). Building with AI agents? Read [For AI agents](https://www.weave.directory/docs/agents). Agents can fetch these docs as plain text: [/docs/llms.txt](https://www.weave.directory/docs/llms.txt) (an index) or [/docs/llms-full.txt](https://www.weave.directory/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.

```bash
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.

| | Git | Weave |
| --- | --- | --- |
| Unit of change | Lines in files | Symbols: functions, classes, constants, JSON keys |
| Who may change code | Anyone, on their own copy | Anyone; changes to an **owned** symbol become a **suggestion** to its owner |
| Staying in step | Fetch and merge when you choose | Real-time sync; `weave sync` or `weave watcher` follow the head |
| Two people change the same thing | Merge conflict; someone resolves markers before continuing | Never blocks: the newer version stays, the other goes to its author as a suggestion; a rejected one becomes a resolution point with both versions |
| Two people change different functions in one file | Usually merges, sometimes conflicts | Never clashes: symbols are independent |
| A unit of work | Commit message | Stitch with an **intent** and a **why**, plus optional **decision records** |
| Lines of work | Branches merged in one step | Workstreams in a chain; stitches **promoted** up one at a time and **inherited** down automatically |
| Rewriting history | Rebase, reset, force-push | Never: heads only move forward; revert and undo add new entries |
| AI agents | Share a person's identity | First-class authors with their own sessions, tokens, drafts and path limits |

### Coming from git: what to use instead

| If you would… | In Weave |
| --- | --- |
| `git clone` | `weave clone <org>/<repo>` |
| `git checkout -b feature` | `weave workstream new feature --from main` |
| `git checkout main` | `weave checkout main` |
| `git add` / `git commit` | `weave add`, then `weave stitch -i "…" -w "…"` |
| `git push` | Nothing: a stitch is sent when you stitch (`weave push` only sends stitches sealed while offline) |
| `git pull` | `weave sync` (or let `weave watcher` do it) |
| Open a pull request and merge | `weave promote <stitch> --to <parent>` |
| Resolve a merge conflict | Usually nothing. For a **change request**: `weave cr resolve <id> this\|other\|edit`. For a **resolution point**: `weave resolve <tag> head\|copy\|edit` |
| `git log` / `git blame` | `weave timeline`, `weave log`, `weave log --symbol <file::symbol>` |
| `git revert` | `weave revert <stitch> --why "…"` or `weave undo` |
| `git stash` | `weave hibernate` / `weave resume` |
| `git tag` | Tags on the server API (`POST /api/weave/{repoId}/tags`) |

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](https://www.weave.directory/docs/api#git-import-and-mirrors)).

## 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

| Stage | Where it lives | Who sees it |
| --- | --- | --- |
| **Draft** | On your device, per person or agent (`.weave/drafts/`) | Only you. Never sent anywhere. |
| **Stitch** | Sealed and sent to the server with an intent and a why | The server checks it |
| **Weaved** | Part of the workstream; the head moved | Everyone on the workstream |

**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](https://www.weave.directory/docs/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](https://www.weave.directory/docs/decisions-and-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](https://www.weave.directory/docs/agents).

## Glossary

| Term | Meaning |
| --- | --- |
| **workstream** | A line of work (`main`, `preprod`, `dev`, `feature/x`). Has a parent (except `main`) and settings for ownership and inheritance. |
| **head** | The current weaved state of a workstream (a 64-hex state id). |
| **draft** | Your private, in-progress changes on this device, by symbol. Never sent. |
| **stitch** | A sealed change with an **intent** (what) and an optional **why**. |
| **weave / weaved** | The weave check accepted a stitch; the workstream head moved. |
| **weave check** | The server's check of a stitch: base, ownership, clashes with newer work, that every operation applies and every file still parses. |
| **symbol** | A named definition: function, method, class, variable, import, JSON key. Named `file::qualified::name`. |
| **claim** | Taking ownership of files or symbols for a while. |
| **owner** | The holder of the most specific live claim on a symbol. Only the owner changes it directly. |
| **lease** | How long a claim lasts unless renewed (server default 10 minutes). |
| **part label** | A claim's feature text of the form `part:<id>`, shown by `weave owners`. Builders use it to say which part of a build owns a file. |
| **suggestion** | A change to a symbol someone else owns, or one that clashes with their newer work; it goes to them to accept or reject. |
| **clash** | A change based on a version someone else has replaced since (`lost_update`), or one that puts back what they replaced (`reverts_newer_work`). Routed as a suggestion, never refused. |
| **resolution point** | Both versions kept after the owner rejects a clash suggestion: a renamed copy `<name>__rp_<tag>` in the code, or the author's text kept on the point. Resolved with `weave resolve`. |
| **change request** | Two versions of one symbol side by side (from two workstreams, a promotion or a revert), each with author, intent and why, for someone to choose. |
| **promote** | Submit a weaved stitch to another workstream, usually the parent, through its weave check. |
| **inherit** | A child workstream receiving its parent's weaves (`auto` at once, `manual` on `weave refresh`). |
| **integrate** | Build a private integration draft to resolve change requests, then stitch the result. |
| **carry forward** | Move your draft onto a newer head. Automatic, because changes are by symbol. |
| **held edit** | An edit on disk you have not added that clashes with a newer version; `weave sync` leaves it on disk and lists it. |
| **session** | One person's or agent's identity in a checkout: its own draft, active workstream and lock (`--agent <name>`). |
| **decision record** | `.weave/decisions/D-xxxx.toml`: a decision (title, why, constraints, rejected alternatives) anchored to symbols. |
| **notice** | A dependency notice: a signature changed, a name now exists or was removed, in code you use. |
| **operation log** | The append-only, hash-chained record of every action (`weave log`). |
| **agent token** | A short-lived (`wva_…`, ≤ 24 h) token for a registered agent, acting for the person who issued it. |
| **path scope** | Glob patterns an agent may write to; writes outside get `403 path_out_of_scope`. |
| **lawful purge** | Removing content (a leaked secret, personal data) from all history without breaking any hash. Needs two admins. |