Documentation

1. Install & Initialize

# macOS and Linux
curl -fsSL https://weave-cli.com/install.sh | sh

# Windows (PowerShell)
irm https://weave-cli.com/install.ps1 | iex

weave --version                    # weave 0.1.0

cd my-project
weave init --local

weave login                        # prompts "Enter your Personal Access Token"
cd my-project
weave init --local                 # creates .weave/ (needed before 'weave remote add')
weave remote add origin https://www.weave.directory/<org>/<repo>   # names the repository
weave init --server https://api.weave.directory

weave ignore              # list built-in defaults + .weaveignore entries
weave ignore add "**/*.log"
weave ignore remove "**/*.log"

2. Quickstart

Every step works in local mode, offline. Changes move draft → stitch → weaved.

weave init --local
weave status                       # edits on disk not added yet
weave add .
weave stitch -i "First version" -w "start of the app" -y

weave workstream new feature-x
# ...edit app.py...
weave add .
weave stitch -i "Friendlier greeting" -k feat
weave status                       # Promotion to 'main': <stitch> ... [promotes cleanly]

weave promote <stitch> --to main
weave checkout main
weave timeline                     # ... (promoted from 'feature-x')
weave log                          # what every person and agent did

weave revert <stitch> --why "broke the kiosk layout"
weave undo

3. Concepts

symbol

A function, method, class, variable, import or other named definition: the unit of change. Line positions never matter.

workstream

A line of work. Everyone on the same workstream stays in sync. The default is the main workstream, main.

draft

Your private work in progress, on this device. Never synced.

stitch

A sealed, complete edit: your draft (or part of it) with an intent and a why.

weave / weaved

The weave check publishes a stitch to the workstream and moves the workstream head. Weaved means deployable for that workstream.

workstream head

The current weaved state of a workstream.

owner

The person or agent who owns a symbol. Only the owner changes it directly.

claim / lease

Taking ownership of symbols or files, held for a renewable period.

suggestion

A change you made to a symbol someone else owns; the owner accepts or rejects it.

promote

Submit a stitch weaved in one workstream to another (usually its parent), where it goes through that workstream’s weave check.

inherit

A child workstream receiving its parent’s weaved stitches, automatically or on weave refresh.

integrate

Resolve change requests in a private integration draft, then stitch the result.

change request

Raised when the same symbol changed differently in two workstreams; resolved by picking one side or editing, with both sides’ why shown.

carry forward

Moving your draft onto a newer workstream head. Automatic, symbol by symbol.

files on disk

Ordinary files rendered from symbols, so editors, compilers and builds keep working.

weave status shows your draft by symbol, edits on disk not added, stitches waiting, open change requests and promotion status. Use weave stitch --only <file|file::symbol> to seal part of your draft, weave draft drop <target> to take changes out of it, weave cat <path> [--workstream <ws>] [--draft] to print a file as weaved, and weave mv a.rs::f b.rs to move a file or symbol as an explicit operation.

4. Owners & Suggestions

Connected to the hosted service, every symbol has at most one owner. Claim symbols, files or globs (expanded locally); a claim is all-or-nothing and held under a lease (10 minutes by default) that a running weave watcher renews.

weave claim src/auth.rs::login "src/session/**/*.rs" --feature "OAuth login" [--lease 3600]
weave claims [--all]               # who owns what
weave release src/auth.rs::login   # or: weave release --all
weave start "Refactor login to OAuth"   # the service predicts and claims symbols for an intent

You can still edit anything. When you stitch, changes to symbols someone else owns are routed to them as suggestions instead of failing; the rest weaves. Your edits stay in your draft, marked awaiting <owner> in weave status, until the owner decides.

weave suggestions                  # waiting for you, and yours waiting for owners
weave suggestions show <id>
weave suggestions accept <id>      # weaved, credited to its author
weave suggestions reject <id> --reason "keep the sync API"
weave suggestions resubmit <id>    # your rejected or stale one, carried forward

When a weave changes a symbol's signature, the owners of its callers are told. Use weave sync to fetch new weaves and weave push to submit stitches sealed while the service was unreachable. weave watcher, run in the checkout, starts weave-watcher in the background (it prints its pid): it keeps files on disk in step with the workstream, renews your leases and re-indexes saved files for search. weave hibernate / weave resume park your draft and bring it back, in either mode.

5. The Workstream Chain

Workstreams form a chain such as prod → dev → feature, where weaved means deployable for that workstream. Work moves one stitch at a time: promote upward, inherit downward.

weave workstream new feature-auth --from dev --ownership repo --inherit auto
weave workstream list
weave checkout dev                 # or: weave workstream switch dev
weave promote <stitch> --to dev [--with-deps]
weave refresh                      # inherit = manual: receive parent weaves now

• --ownership repo (default): one owner per symbol across every repo-mode workstream. workstream: the workstream has its own owners, for example a sandbox.
• --inherit auto (default): parent weaves arrive immediately for symbols you haven't changed. manual: held until weave refresh.
• A stitch that relies on earlier, unpromoted stitches can't be promoted alone; --with-deps promotes them together.

A symbol changed differently on both sides raises a change request as soon as it happens. Resolve it in a private integration draft, build and test, then stitch.

weave cr list [--all]
weave cr show <id>                 # both sides, each with intent and why
weave integrate <id|workstream>    # private integration draft
weave cr resolve <id> this|other|edit [--text "..." | --from-file <path>]
weave stitch -i "Take dev's formal greeting"
weave status --impact <workstream> # symbols changed differently there

6. Revert, Log & Undo

Workstream heads only move forward. weave revert weaves the inverse operations; a symbol changed again since is not overwritten but becomes a change request. The operation log is append-only and hash-chained. weave undo reverses your own action (a claim is released, a weave is reverted) and is itself logged.

weave timeline [<workstream>] [--limit 100]
weave revert <stitch> --why "broke MFA"
weave log [--actor <user>] [--by-agent <agent>] [--workstream <ws>] [--symbol <symbol>] [--limit 30]
weave log --verify                 # check the hash chain
weave undo [<entry>]

7. Decisions & Agents

A decision record says why the code is the way it is. Records are files in .weave/decisions/<id>.toml, anchored to symbols and versioned with the code: they go draft → stitch → weaved, and are promoted, inherited and reverted with it. weave stitch --why drafts one in the same stitch. A [D-xxxx] tag in a code comment is a strong anchor.

weave decision add -t "Greeting stays one line" -w "the kiosk wraps at 40 chars" \
  --on app.py::greet --alt "multi-line banner" --comment   # inserts "why: ... [D-xxxx]"
weave decision list [--all | --status needs_review]
weave decision show D-a8fc
weave decision for greet [--radius 1] [--budget 800]       # ~25 tokens per decision
weave decision search "kiosk" [--near greet] [--budget 600]
weave decision impact app.py::main [--depth 1]
weave decision review [--dry-run]                          # anchors changed since?
weave decision review D-a8fc --accept
weave decision supersede D-a8fc -t "..." -w "..."
weave decision retire D-a8fc --reason "..."

Agents

Set WEAVE_AGENT (or pass --agent <name>, plus --agent-model) and each agent gets its own active workstream and private draft on the device, and is credited on its stitches and in the log. weave mcp serves decision and thread tools over stdio: decisions_for, decision_search, decision_get, impact, decision_propose, decision_review, thread_show, thread_add and more.

weave install-claude                     # pointer in CLAUDE.md
claude mcp add weave -- weave mcp
WEAVE_AGENT=claude weave status          # or: weave --agent claude status

Threads and enrich

Threads are short per-symbol behaviour notes in .weave/threads/; run weave index first. weave enrich asks an LLM, with your own key, to propose baseline notes.

weave index
weave thread show login --depth 1
weave thread add login "token refresh is lazy: eager refresh doubled auth traffic"
weave enrich --file src/auth.rs [--provider anthropic|openai|gemini]

8. Configuration

Weave talks to two hosted URLs: the platform (weave login, repository lookup), default https://www.weave.directory, and the server (workstreams, claims, search, the watcher), default https://api.weave.directory. Each resolves first match wins: an explicit flag (weave login --url, weave init --server), the environment variable, .weave/config.json in the checkout, ~/.weave/config.json, then the default. For the platform URL the global file's older url key is also read (after platform_url).

An older config can override the defaults. weave login saves the URL it used as both platform_url and url, and weave init --server saves server_url in the checkout. Running weave login without --url reuses whatever is stored, so a config from an earlier setup keeps pointing there. To point it back at the hosted service (and unset WEAVE_PLATFORM_URL / WEAVE_SERVER_URL if you exported them):

weave config platform_url https://www.weave.directory   # takes precedence over an old url key
weave config server_url https://api.weave.directory
weave init --server https://api.weave.directory         # in each checkout: rewrites its server_url

weave config <key> <value> sets a string key in ~/.weave/config.json (written with owner-only permissions). A .env file in the current directory is loaded automatically.

9. Retired Commands

These belonged to the earlier line-based model and are hidden from weave --help. Running one prints its replacement (inbox still lists your suggestions). simulate-change was removed entirely.