Skip to main content

One vault, many machines

The same vault lives on the owner's laptop and on the box. Git keeps them the same. No sync app is involved.

Where you see it​

This is invisible plumbing. The owner notices it only when it works: a note written on the laptop in the morning is known by the box by lunch.

What happens, step by step​

  1. The owner, on the laptop, asks the agent to update the price list.
  2. Before touching anything, the agent pulls the newest copy of the vault with git pull --rebase --autostash (get the latest, and keep local edits safe while doing it).
  3. The agent edits the file.
  4. It saves only the files it changed (a commit) and pushes them.
  5. Later, the box pulls the same way. Now both machines have the new price list.

What powers it​

PartWhat it does
gitMoves changes between machines and keeps every version.
doctrine.mdThe rule set for running one vault on many machines.
Each machine's own CLAUDE.md mapA private file that says where things live on that machine.
vault-lintA weekly checker that catches machine details leaking into shared files.
Only git syncs the vault

Never point iCloud, Dropbox, or OneDrive at the vault. Two sync tools fighting over the same files can lose work.

Why it works this way​

The vault can have several writers at once: the owner's computers and the box, each with its own agent. So every agent pulls first and saves only the files it changed. It never sweeps up someone else's half-done work, and it never overwrites a newer copy.

The one principle

The machine answers questions about itself. The vault holds only what is true on every machine.

Here is what that means in practice. A website's code lives in a repo (a code folder tracked by git), say maple-cafe-site. The vault records the repo's name. It never records where that repo sits on a disk, because that is different on the laptop and on the box.

So when the agent needs the repo, it does two things:

  1. It reads the repo's name from the vault.
  2. It reads its own machine's private map, which says "repos live here on this machine," and looks there.

If the repo is there, it edits it. If the folder is missing, the repo still exists. It is just not copied onto this machine yet, so the agent offers to copy it. It never reports "that site does not exist" because one folder was empty.

The same rule covers anything one quick command could answer, like "is this tool installed here?" The vault does not write down the answer. It names the command, and the machine runs it and answers for itself. A fact written into a file goes stale. A fact checked live does not.

Connected to​