The Weave Workflow
Symbols are the unit of change, every symbol has an owner, and work moves draft → stitch → weaved along a chain of workstreams. Here is the whole flow, with the commands that drive it.
Install, sign in, connect
Use Weave offline in local mode, or connect to the hosted service to share workstreams with your team.
1. Install the CLI
macOS and Linux. Windows and direct downloads are on the install page.
2. Work locally
Workstreams, the weave check and the operation log live in .weave/ on your device. You own every symbol.
3. Or connect
weave login takes a Personal Access Token from your Weave account. Drafts still never leave your device.
draft → stitch → weaved
Draft
Private
weave add captures your edits from files on disk, by symbol. Drafts never leave your device or agent, so nobody sees half-done work.
Stitch
Sealed
weave stitch seals the draft into one complete edit with an intent and a why, and submits it for the weave check.
Weaved
Deployable
The server checks ownership and symbol hashes, then publishes the stitch and moves the workstream head forward. Weaved means deployable for that workstream.
Owners and suggestions
Every symbol has one owner. Claim symbols or files and you hold them under a renewable lease. Within a workstream, ownership and symbol hashes prevent clashes before they happen.
Change a symbol someone else owns and that part of your stitch becomes a suggestion to them, carrying your intent and why. Your edit stays in your draft, marked as awaiting the owner, until they accept or reject it. When an owner changes a function's signature, the owners of its callers are notified.
The workstream chain
Workstreams form a chain such as prod → dev → feature/auth. Weaved stitches are promoted upward one at a time and pass each workstream's own weave check; a stitch that depends on an earlier one is promoted together with it. Children inherit their parent's weaved stitches automatically, or on weave refresh.
When the same symbol changes differently on both sides, a change request opens as soon as it happens. weave integrate builds a private local draft with both versions side by side, each with its intent and why. Pick this, other, or edit; build and test; then stitch.
Each workstream sets ownership (shared repo-wide owners, or its own) and inherit (auto or manual).
Revert, log and undo
History only moves forward. A revert is a new stitch of inverse operations; a symbol changed again since is not overwritten but raised as a change request. The operation log is append-only and hash-chained: claims, stitches, suggestions, change requests and promotions, by every person and agent. weave undo reverses your own most recent action, and is logged too.
AI agents and decision records
Agents work alongside people under the same rules. An agent identifies itself with --agent or WEAVE_AGENT, gets its own active workstream and private drafts, and is credited on its stitches and in the log.
weave stitch --why records a decision next to the code, versioned with it in .weave/decisions/ and anchored to symbols with [D-id] comments. Over MCP, agents retrieve the decisions relevant to the code they are touching within a token budget, before they change it.
On the web
The web platform shows the same state as the CLI: workstreams and their weaved stitches, suggestions, change requests, the operation log, a symbol ownership panel with history, and notifications. Saving a file in the web editor makes a stitch; if you don't own a symbol, it becomes a suggestion.
If you are coming from git
Files on disk are ordinary files, so editors, compilers and builds keep working. What changes is how work is tracked and shared.
| git | Weave |
|---|---|
| Lines and files | Symbols: functions, variables, imports |
| Anyone edits anything; conflicts found later | Each symbol has an owner; others send suggestions |
| Branches merged in one big step | Stitches promoted one at a time along a workstream chain |
| Conflict markers in your files | Change requests showing both sides' intent and why |
| Commit messages | Intent, why and decision records anchored to symbols |
| History rewrites (rebase, reset) | History only moves forward: revert and undo add new entries |