Get started

From a git repo on your computer to your first patch on main, in about ten commands.

1. Get seam

Seam's command is seam, from the npm package @heyquilt/seam. It needs Node.js 22 or newer. It is its own command: the Quilt app's quilt command has nothing to do with source control.

$ npm install -g @heyquilt/seam
$ seam --version

Run it without installing with npx @heyquilt/seam log. The verbs are quilts, square, checkout, status, commit, log, show, diff, merge, rebase, revert, cherry-pick, blame, resolve, cat, ls, import, export and events; seam help lists them.

Sign in with your heyquilt.com account. The command opens a page in your browser where you approve this computer; --no-browser prints the link instead. seam keeps its sign-in in ~/.seam, apart from the Quilt app's, and renews it by itself.

$ seam login
To sign in, open this page and approve this computer:

  https://heyquilt.com/…

Check it shows the code …. Waiting…
Signed in as Ada Lovelace (ada@example.com).

Every command then talks to https://api.heyquilt.com as you. Agents sign in with a key of their own instead: see For agents.

3. Bring in a git repo

Import makes a new quilt from the history of the repo's HEAD. Every commit on its first-parent chain becomes a patch on main, in order. The side commits of a merge become the commits of that patch's square, so nothing is lost. Authors are kept.

$ seam import git ./my-app --validate
Importing 782 patches (1335 commits in all) into my-app…
  58 patches, 100 commits
  …
Imported 1335 commits (782 patches on main) into my-app (019a1f2c-…). Validated 782 trees against git.

The quilt is named after the folder. --into <slug> picks another name.
--validate checks, after the import, that every patch holds exactly the files of its git commit.
The import runs on your computer: it reads the repo with git and uploads only what the server does not have yet.

To start with nothing instead, make an empty quilt. Its main starts at an empty root commit.

$ seam quilts new my-app
Made quilt my-app (019a1f2c-…).
$ seam quilts
my-app  019a1f2c-…  (admin)

4. Open a square and check out a block

A square is your own piece of work. Open one from the tip of main and check it out into a new folder in one step. Paths after -- pick the block: only those folders and files are written. Leave them out to get the whole quilt.

$ seam square open "Fix sign-in" --quilt my-app --dir fix-sign-in -- src docs
sq:1a2b3c4d "Fix sign-in" · open · no commits yet · held by person:7f3e…
Checked out into /Users/ada/fix-sign-in.

You can also open the square first and check it out later, or check out any revision to read it. A checkout of a revision is read-only, because only a square takes commits.

$ seam checkout sq:1a2b3c4d --quilt my-app --dir fix-sign-in -- src
$ seam checkout patch:780 --quilt my-app --dir old-copy

A checkout goes into an empty folder. Inside a block folder, seam checkout <square or revision> switches the folder over, once its changes are committed.

5. Edit and commit

Edit the files with any editor or AI tool. Inside the folder you do not need --quilt: the quilt and the square come from .seam/block.json.

$ cd fix-sign-in
$ seam status
On square sq:1a2b3c4d "Fix sign-in" · open · no commits yet · held by person:7f3e…
Block: src, docs at 4d5bb0f2aacd
Changes not yet committed:
  modified  src/auth.js
$ seam diff
$ seam commit -m "Sign-in keeps the session"
Committed 9e8d7c6b5a49 "Sign-in keeps the session"
square sq:1a2b3c4d "Fix sign-in" · open · head 9e8d7c6b5a49 · held by person:7f3e…

There is no staging area: seam commit takes every changed file in the block. Name paths to commit only some: seam commit -m "Docs" docs/.
New files are picked up without an add step. The folder's top-level .gitignore is read, and .git, .quilt and node_modules are always left out.
A commit is on the server the moment it is made. There is nothing to push.

6. Merge into main

In the block folder, seam merge merges the square into its line. The server replays the square onto the current tip of main as one commit and gives it the next patch number.

$ seam merge --dry-run
Would merge as patch main:783 (no file touched on both sides).
$ seam merge
Merged as patch main:783 (5f4e3d2c1b0a).

The patch's message is the square's title followed by its commit messages; -m sets your own. If the square clashes with a patch that merged after you opened it, the merge is refused and the clash is kept in your square to settle. Conflicts explains what to do.

7. Read the history

$ seam log --oneline -n 3
5f4e3d2c1b0a [main:783] Fix sign-in
a1c5c9d77b1a [main:782] Source dashboard: its own app
4d5bb0f2aacd [main:781] Session email is live
$ seam log -n 5 -- src/auth.js
$ seam show patch:783 --stat
$ seam diff patch:781 patch:783 --name-only
$ seam blame src/auth.js
$ seam cat README.md@patch:700
$ seam ls main src

Outside a block folder, add --quilt my-app to any of these. Add --json to any command to get the server's record instead of text.

A quilt is private to its members. Its admins add people and agents by member id, at read, write or admin.

$ seam quilts add agent:5c1e… --level write --quilt my-app
agent:5c1e…: write

An agent's id is on its row under Agents on heyquilt.com. A member can see their own id under you in seam quilts show <quilt> --json.

9. Back to git, any time

Export writes a line's patches as commits on a branch of a plain git repo, so CI and deploys that expect git keep working. It is one way: run it again and it adds the new patches.

$ seam export git ../my-app-git --quilt my-app
Exported 783 patches to main in ../my-app-git: main is 3c9a… (patch 783).

More on import and export in Compare to git.