Skip to main content
Two questions, in this order, because a brain name means nothing until it is known whose vocabulary it belongs to. Which project — a vitruvio.toml. First one wins:
  1. --config FILE — that file, verbatim.
  2. --project NAME — by name, from anywhere. Registered by project init or project register.
  3. $VITRUVIO_CONFIG or $VITRUVIO_PROJECT — the same two answers, from the environment.
  4. The nearest vitruvio.toml, walking up from the working directory.
Which brain, inside that project:
  1. --brain NAME — a brain the project declares — or --brain PATH.
  2. $VITRUVIO_BRAIN — how a container, a CI job, or one agent’s session says it without editing files.
  3. [brain].path in the project file.
  4. The project’s only brain, when it holds exactly one.
  5. What vitruvio brain use last recorded for this project.
The file layers resolve a relative path against the file’s directory, never against the working directory: a config that means a different brain depending on which subdirectory you happened to be in is not a reproducibility artifact. One extra rule worth knowing: when --brain names a brain outside the current tree and the walk-up finds nothing, the walk restarts beside the brain. Without it, the vitruvio.toml that brain init had just written would be ignored by the very next command.

​
Selecting a brain by name

The name is tried before the path, so a stray ./optics directory cannot shadow the project member. Working on the wrong brain in silence is the failure that ordering exists to prevent. $VITRUVIO_BRAIN=optics works the same way, which is how a container or a CI job picks a subject without editing a file. A project holding exactly one brain needs no flag at all.

​
Selecting the project too, from anywhere

project init registers the project’s name on this machine, so --project reaches it from any directory:
Those two commands share no mutable state, so they can run at the same time, in different terminals. That is the point: one invocation states its whole context — project and brain — and nothing about it depends on the working directory or on anything another terminal did. Three agents, three projects, three subjects. $VITRUVIO_PROJECT=coursework is the same answer from a shell profile or a container, and pairs with $VITRUVIO_BRAIN=mechanics. Exporting both once is how one agent’s session pins itself to one subject. Managing the registry:
It is a registry of names: every entry is a path to a committed vitruvio.toml, and everything about a project is still read from there. Nothing is configured in it, so losing it costs the --project shorthand and nothing else.

​
There is no “active brain”

vitruvio brain use still exists, and it is now scoped to one project:
A choice made in coursework reaches no other project. This used to be a single machine-wide pointer, which had two problems: two terminals could not disagree about which brain they were on, and worse, a pointer left behind in one project answered for a different project whose brains were all addressed by name — a write into the wrong subject, in silence, with no undo. So it is a per-project convenience for a shell, and nothing more. In a script or an agent, pass --project and --brain: they are the only layers that survive being read by somebody else. A project that declares brains therefore asks by name instead of guessing: