Quickstart

From a new account to your first weaved stitch, in about ten minutes. You need macOS or Linux (Windows: see the installer page).

1. Create your account#

1. Go to weave.directory/signup. Enter Full Name, Email and Password (at least 8 characters), tick the terms box and click Sign Up.
2. Open the email from Weave and click the link. On the Verify your email page click Verify email. You need a verified email to create organizations and access tokens.
3. Sign in. The first time, pick the role that best describes you (Developer, Team Lead, Reviewer or Manager) and click Select.

Turn on two-factor authentication now if you will own or administer a team organization: owners and admins of an organization need 2FA to administer it (personal organizations are exempt). Go to your avatar → Settings → Account → Set up 2FA, scan the QR code and enter the 6-digit code.

2. Create an organization#

In the web UI: click + in the header → Organization (or go to /orgs/new). Enter an Organization Name and an Organization URL (weave.directory/<slug>), then click Create Organization.

Or with the API, using a personal access token with the org:admin scope (step 4 shows how to make one):

curl -s https://weave.directory/api/v1/orgs \
  -H "Authorization: Bearer $WEAVE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "slug": "acme"}'

{ "id": "clx…", "slug": "acme", "name": "Acme" }

The slug is lower-case letters, digits and hyphens. A taken slug answers 409 conflict.

3. Create a repository#

In the web UI: on your organization's page click New Repository (or + → Repository). Choose the Owner, a Repository Name, an optional description, what to Initialize with (Default (README), Empty, Next.js / React, Rust / CLI or Python) and the Visibility, then click Create Repository. You land on weave.directory/<org>/<repo>. The repository has two workstreams, main and dev (dev's parent is main), and the template's files are the first stitch on main.

Or with the API (scope org:admin, and you must be a member of the organization):

curl -s https://weave.directory/api/v1/orgs/acme/repos \
  -H "Authorization: Bearer $WEAVE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "shop", "description": "Our web shop", "private": true}'

{ "id": "cm3k…", "name": "shop", "org": "acme", "slug": "acme/shop", "private": true,
  "workstreams": ["main", "dev"], "warnings": [] }

• id is the repository id. The Weave server API (/api/weave/{repoId}/…) takes this id, not org/name.
• workstreams defaults to ["dev"]; every listed workstream is created with main as its parent. Want main ← preprod ← dev instead? See Workstreams.
• template defaults to "empty" over the API.

4. Create a personal access token#

Go to your avatar → Settings → Access Tokens. Under Generate New Token give it a Name, an Expiration (30, 60 or 90 days, or 1 year), the Scopes you need (repo:read and repo:write are ticked by default) and the Repository access, then click Generate Token. Copy it now — it is shown once. Personal access tokens start with weave_.

5. Install the CLI and sign in#

curl -fsSL https://weave-cli.com/install.sh | sh
weave --version          # weave 0.4.0
weave login              # paste the token; it is checked and saved in ~/.weave/config.json

echo "$WEAVE_PAT" | weave login reads the token from stdin. In CI or an agent sandbox you can skip weave login: set WEAVE_TOKEN and weave clone, add, stitch and sync work without prompts.

6. Clone the repository#

weave clone acme/shop
cd shop
weave status

weave clone <org>/<repo> [dir] [--workstream main] [--server URL] downloads the head of the workstream in one request, writes the files, verifies them against the head and sets up .weave/ connected to https://api.weave.directory. weave status is clean straight away. With --json (values shortened):

{ "repo": "acme/shop", "dir": "shop", "workstream": "main", "head": "4218fab7…", "files": 3,
  "bytes": 1840, "server": "https://api.weave.directory", "state_included": true, "warnings": [] }

Already have a folder with code? Run weave init --server https://api.weave.directory in it instead (name the repository first with weave remote add origin acme/shop if your account can reach several).

7. Edit, add and stitch#

Work on dev, then promote to main:

weave checkout dev

Edit a file with your editor, for example add a function to src/cart.ts. Then:

weave status                 # your draft, and edits on disk not added yet
weave add                    # record the edits in your draft, by symbol
weave stitch -i "Add a cart total helper" -w "checkout shows the total before tax"

• -i/--intent (required) says what the change is for. -w/--why keeps the rationale with the change and drafts a decision record anchored to the symbols you changed; you confirm it (-y records it without asking).
• The weave check runs at once. When it passes, the stitch is weaved and the head of dev moves.
• If part of it touched a symbol someone else owns, that part goes to them as a suggestion and the rest weaves. weave status marks it awaiting <owner>.

weave stitch --json prints the outcome:

{ "result": "weaved", "workstream": "dev", "stitch": "9c1e…", "head": "77ab…",
  "suggestions": [], "routed": [], "held_back": [], "warnings": [] }

8. Promote to main#

weave timeline               # weaved stitches of dev, newest first, with their ids
weave promote 9c1e --to main # a prefix of the stitch id is enough

The stitch goes through main's own weave check and keeps its author, intent and why. If it relies on earlier stitches that are not in main yet, Weave lists them and asks; --with-deps promotes them together.

9. See it on the website#

Open weave.directory/<org>/<repo>:

• Code shows the files of the selected workstream (pick it with the workstream selector) and a latest stitch link.
• Weaved (/<org>/<repo>/stitches) lists the weaved stitches with author, intent and why, with Promote to {parent} and Revert actions.
• Workstreams, Suggestions, Change requests and Log show the rest.

You can also stitch from the browser: New → New File, or edit a file, fill in What is this change for? and click Stitch.

Next steps#

• Work with others: claims, suggestions and clashes.
• Set up main ← preprod ← dev: Workstreams.
• Run AI agents on the repository: For AI agents.
• Keep a terminal following the head: weave watcher renews your claims, keeps files on disk in step and prints messages for you.