README
¶
vat
Git records each repository. vat records what happened across them.
Your repositories are the body, vat the vessel, vat brain the memory
suspended inside it — where nothing counts as a fact until someone records when
they last checked.
An agent moved order cancellation into payments and console together.
Each repository's own git log is complete, and neither answers the one
question that actually matters six months later:
$ vat changeset show CS-0001
CS-0001 Move order cancellation to v2
status: closed · opened 2026-05-02 · 3 days
acceptance: cancel-then-refund passes end to end
Repositories
REPOSITORY RETURN TO VERIFIED AT CHECKS
payments 3f9a1c2e a71c93d0 1 check passed
console 8b2e0d19 5c1f80ab 1 check passed
Two revisions, verified together, with the return point still on file. That
record is what vat adds on top of Git — not a replacement for it. →
The full walkthrough
Two ways in.
Several repositories, worked in together. One manifest, one place to run from, and a record of which revisions were verified together — the problem below. → keep reading.
One repository, with an agent working in it. vat harness keeps one role
body and one procedure body, generates each runtime's file from them, and fails
the build the day a copy diverges. → docs/HARNESS.md
vat fit will tell you which of the five layers you do not need yet.
The problem
~/acme/
├── payments/ ← git repo
├── console/ ← git repo
└── docs/ ← git repo
$ cd payments
$ claude
The moment a session opens inside payments, that becomes the agent's whole
world. You are working on acme; it thinks it is working on payments, and
everything on the other side of ../ is an external path it has to be told
about, one relative reference at a time. vat's answer is to start one level
up:
$ cd ~/acme
$ vat init --adopt
$ codex
Now the workspace is the project. The repositories are its parts. Three specific things about that arrangement are otherwise written down, assumed, or remembered — and nothing checks them:
- What crossed the boundary. An API change shipped across three
repositories. Each
git logis complete and none of them is the answer: nobody can say which three revisions were verified together, or how to get back — andfor r in */; do git -C "$r" pull; donereports success while one repository silently stashed your work. - The contract your agents read. A session at the parent directory can see
every repository, which is the point and also the hazard — reading them all
is not permission to write to any of them. Meanwhile the same role is defined
in
.claude/agents/and.codex/agents/, and nobody diffs a prompt. - The facts both of them rely on. A doc says the payments service "has retry-safe ordering." It was true when someone wrote it. Nobody has checked since, and it is quoted as current fact weekly, by people and by agents that cannot tell that nobody has.
vat turns each one into a check that runs:
$ vat lint
FAIL workspace/gitignore-drift · console 1 governed repository is not excluded by .gitignore; a workspace commit would swallow it
→ vat lint --fix
FAIL harness/adapter-drift · .codex/agents/planner.toml runtime adapter no longer matches its role definition in .agents/roles
→ vat harness render
WARN brain/source-revision-drift · G-0014 payments has moved 47 commits since this was observed at 3f9a1c2; re-check, do not assume it broke
WARN changeset/open-too-long · CS-0007 open for 31 days, past the 14-day limit; repositories are mid-contract-change with no closing evidence
Result
FAIL lint 2 errors, 2 warnings across 41 rules
2 of these can be repaired with `vat lint --fix`.
Who this is for
You work across several repositories, and so do your agents. One manifest, one place to run from, a written boundary per repository so a session at the parent directory cannot edit its way across one by accident, and a record of which revisions were verified together.
You use coding agents on a codebase you care about. One repository is
enough. vat harness generates the per-runtime adapters from one role body so
Claude Code and Codex cannot drift apart. If you already have .claude/agents/
or .claude/skills/, vat harness adopt moves what you wrote under that
contract in one command.
Your team keeps re-deriving what it already decided. vat brain records a
fact with the revision it was read from, and demotes it when nobody re-checks
it. Not a wiki, not a vector store: a claim that expires.
Run vat fit and it will tell you which of those you do not need yet.
What this is not
Being clear about the neighbours is more useful than pretending there are none.
| If what you want is | Reach for |
|---|---|
parallel git pull across many repositories |
a shell loop, mu-repo, meta, gita |
| one build graph and task runner over many projects | Nx, Turborepo, Bazel |
| a place to file architecture decision records | adr-tools, Log4brains |
| semantic recall over your documents for an agent | a retrieval layer — and point it at vat brain, which decides what is canonical |
| portable agent memory, so what one tool learned another can read | one of the several markdown-and-folders memory formats now converging on that — vat brain is readable the same way, and answers a different question |
| agent instructions for one tool | that tool's own directory, until there is a second runtime or a second copy |
| a history of what crossed between repositories, and rules that fail loudly when reality moves away from them | vat |
On agent instructions. The format is barely the problem — .claude/agents/
and .codex/ are both Markdown with front matter. The problem is the second
copy: the moment a procedure exists in two runtimes, the one an agent happens
to load decides what it does, and neither looks less authoritative. See
docs/HARNESS.md.
On agent memory. Taking memory out of the tool and writing it as folders
and markdown is easy; the hard half is who is allowed to write a fact, and
how does a reader know it is still true. Portability is the format vat
shares with the rest; trust is the contract it adds. See
docs/BRAIN.md.
vat is not a build system, and it will not make your agent smarter. It gives
the agent a boundary it cannot cross by accident, and leaves behind an account
of what actually happened across your repositories.
Install
# Homebrew — macOS and Linux
brew install takealook97/tap/vat
# Go 1.25+
go install github.com/takealook97/vat/cmd/vat@latest
Or download an archive for macOS, Linux, or Windows from Releases. Every release also publishes SHA-256 checksums, a CycloneDX SBOM per platform, and a signed build-provenance attestation:
gh attestation verify vat_darwin_arm64.tar.gz --repo takealook97/vat
A checksum says an archive matches a list published beside it by whoever published the archive. The attestation is a signed statement of which commit and which workflow run built it, and the signature is not the publisher's to forge.
One binary. One dependency (gopkg.in/yaml.v3). No runtime, no daemon, no
config server. vat shells out to your git, so your credential helpers,
hooks, and host config apply unchanged.
60 seconds
$ cd ~/work # a folder with several repos already cloned
$ vat init --adopt --name acme
OK vat.yaml 4 repositories enrolled
OK .gitignore governed repositories excluded from the root history
OK .agents/skills/before-cross-repo-work/SKILL.md seeded
OK .agents/skills/consult-the-brain-first/SKILL.md seeded
OK .claude/skills/before-cross-repo-work/SKILL.md generated
OK .claude/skills/consult-the-brain-first/SKILL.md generated
OK .codex/skills/before-cross-repo-work/SKILL.md generated
OK .codex/skills/consult-the-brain-first/SKILL.md generated
OK AGENTS.md generated
OK CLAUDE.md generated
OK brain/AGENTS.md generated
OK console/AGENTS.md generated
OK docs/AGENTS.md generated
OK payments/AGENTS.md generated
INFO brain brain · https://github.com/acme/brain.git
INFO console product · https://github.com/acme/console.git
INFO docs docs · https://github.com/acme/docs.git
INFO payments product · https://github.com/acme/payments.git
Next
vat status see where every repository stands
vat doctor judge the environment
vat fit decide which layers are worth adopting yet
$ vat status
REPOSITORY BRANCH REV TREE VS ORIGIN NOTE
brain main 9af189c clean =
console feature 772418c dirty +2 not on main
docs master 3bf4bf2 clean -4
payments main 3bebc3c clean =
4 repositories · 1 dirty · 1 ahead · 1 behind · workspace acme
Run `vat sync` to fast-forward what can be advanced safely.
$ vat sync
REPOSITORY STATE BRANCH REV DETAIL
brain CURRENT main 9af189c
console DIRTY feature 772418c uncommitted changes to tracked files; nothing advanced
docs UPDATED master 1e5b9a0
payments CURRENT main 3bebc3c
1 advanced · 2 already current · 1 left alone on purpose · 0 need attention
Notice what sync did not do: it did not stash console's work, did not
check docs out to main, and did not report success on your behalf. A
colleague who clones the (committed) workspace and runs vat sync gets the
same repositories, on the same branches, with the same contracts an agent will
read. → The staged path in, and how to leave
Documentation
| Walkthrough | one contract change, end to end, across three repositories |
| Adoption | a staged path in, and how to leave |
| Methodology | the full operating model this implements |
| Commands | every command, flag, and exit code |
| Manifest | vat.yaml reference |
| Brain | record schema, lifecycle, and the promotion gate |
| Harness | generated regions, roles, and runtime adapters |
| Changesets | multi-repository atomicity |
| Security model | trust tiers, gates, credential boundaries |
| Spec | the file formats, normatively — what another tool needs to read a workspace |
| FAQ | monorepo, submodules, and other fair objections |
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for
the commit convention ({category}: {description}), the review checklist, and
how to run the suite.
make check # format, vet, race-enabled tests, build
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
vat
command
Command vat is the workspace control plane.
|
Command vat is the workspace control plane. |
|
internal
|
|
|
brain
Package brain implements the reviewed-knowledge layer: atomic records that own one fact each, generated projections over them, and a lifecycle that stops an old claim from quietly remaining "current" forever.
|
Package brain implements the reviewed-knowledge layer: atomic records that own one fact each, generated projections over them, and a lifecycle that stops an old claim from quietly remaining "current" forever. |
|
changeset
Package changeset records the completion evidence for a change that spans several repositories.
|
Package changeset records the completion evidence for a change that spans several repositories. |
|
cli
Package cli wires vat's commands together.
|
Package cli wires vat's commands together. |
|
doctor
Package doctor judges an environment.
|
Package doctor judges an environment. |
|
evidence
Package evidence defines the packet handed to a worker before it starts and the record it must return.
|
Package evidence defines the packet handed to a worker before it starts and the record it must return. |
|
fit
Package fit answers the question a methodology document should answer first and almost never does: at what point is this worth its cost?
|
Package fit answers the question a methodology document should answer first and almost never does: at what point is this worth its cost? |
|
frontmatter
Package frontmatter reads and writes the YAML header of a Markdown file.
|
Package frontmatter reads and writes the YAML header of a Markdown file. |
|
fsx
Package fsx provides filesystem helpers: writes that never leave a half-written file behind, and the rules about what a name may be before it becomes one.
|
Package fsx provides filesystem helpers: writes that never leave a half-written file behind, and the rules about what a name may be before it becomes one. |
|
gitx
Package gitx wraps the git command line.
|
Package gitx wraps the git command line. |
|
harness
Package harness generates and validates the agent contract files of a workspace: the workspace AGENTS.md, each repository's AGENTS.md, and the per-runtime adapters that point at one runtime-neutral role body.
|
Package harness generates and validates the agent contract files of a workspace: the workspace AGENTS.md, each repository's AGENTS.md, and the per-runtime adapters that point at one runtime-neutral role body. |
|
lint
Package lint turns the workspace's rules into checks that run.
|
Package lint turns the workspace's rules into checks that run. |
|
manifest
Package manifest owns vat.yaml: the single declaration of which repositories a workspace governs and under which policy.
|
Package manifest owns vat.yaml: the single declaration of which repositories a workspace governs and under which policy. |
|
metrics
Package metrics answers a question the methodology cannot answer about itself: is any of this working?
|
Package metrics answers a question the methodology cannot answer about itself: is any of this working? |
|
runner
Package runner executes shell commands inside repositories, with the bookkeeping every caller needs: which repository, what was run, how long it took, and what it printed when it failed.
|
Package runner executes shell commands inside repositories, with the bookkeeping every caller needs: which repository, what was run, how long it took, and what it printed when it failed. |
|
syncx
Package syncx implements the workspace update state machine.
|
Package syncx implements the workspace update state machine. |
|
ui
Package ui centralises vat's terminal output so every command reports state the same way: a fixed column layout, a small status vocabulary, and colour that disappears when the output is not a terminal.
|
Package ui centralises vat's terminal output so every command reports state the same way: a fixed column layout, a small status vocabulary, and colour that disappears when the output is not a terminal. |
|
version
Package version exposes build metadata stamped in at link time.
|
Package version exposes build metadata stamped in at link time. |
|
workspace
Package workspace resolves the workspace root and gives the rest of vat a single, validated view of it: where the manifest is, where each repository should live, and which files vat owns.
|
Package workspace resolves the workspace root and gives the rest of vat a single, validated view of it: where the manifest is, where each repository should live, and which files vat owns. |