Goal
A task built in its own git worktree gets a Python environment of its own: a .venv inside the
worktree, built from the project's lock file, with the project installed from the worktree's own
source. Files ship with a branch; an environment does not. Without this, the worktree has no
.venv/bin/pytest, so the test runner python-cli/test-execution.md resolves is missing, and a
run borrowed from the main checkout's environment imports the main checkout's code. With it,
the worktree's .venv/bin/pytest imports the branch's code.
The sections a consumer runs are read in document order: the one line under ## Preconditions,
then ## Bring up, then ## Address. ## Status says whether the environment is there, and
## Tear down removes it.
Opinion
uv builds the environment, from the committed lock file. uv sync --frozen creates .venv
in the project root it is run from and installs exactly what uv.lock pins, without resolving
again and without writing the lock file. Run in the worktree, that root is the worktree, so the
environment is the worktree's own. A project whose pyproject.toml declares a [build-system] is
installed editable from the worktree's source, so an import reaches the branch's code and not the
main checkout's. uv installs no project that declares none; only its dependencies go in.
Nothing is shared with the main checkout's environment. Each checkout has its own .venv.
uv's package cache is shared, and that is fine: it holds downloaded files, not an environment.
UV_PROJECT_ENVIRONMENT is the one setting that moves the environment out of the project root,
so the check refuses while it is set.
The address is the environment's path, not a URL. The consumer requires an address: line.
For a command-line tool there is nothing served, so the address is the resolved path of the
environment .venv/bin/python runs in. It is exported as PLAYWRIGHT_BASE_URL like any
address; a command surface does not read it. root: is the directory holding that environment,
and the consumer stops when it is not the worktree.
Bring-up is a person's choice. uv sync needs the network the first time a package is
missing from the cache, and a second environment costs disk. A task that changes only
documentation has no use for one. The commands are shown once and run on a yes.
Preconditions
- uv is on the PATH. Nothing in this recipe installs it.
- The worktree holds a pyproject file and a committed uv lock file. A frozen sync installs from the lock file and never writes it, so a project with no lock file is refused rather than locked on the fly, which would leave the tree dirty. The remedy is to run uv lock and commit the lock file on the branch the worktree has checked out.
- The uv project-environment variable is unset, so the environment is built at the worktree's own .venv and nowhere else.
- The line runs in a task worktree, never in the main checkout, whose environment is the one a worktree must not touch.
A trap for whoever edits this section: the consumer records every file this prose names in backticks that the branch has changed, and completion puts each one back to its content where the branch started. A task that adds a dependency changes the pyproject file and the lock file. Named in backticks here, they would be reverted at completion and the task's own change lost, so this section names no tracked file in backticks.
The checks a script can make are one line, run in the worktree after ## Files is written and
before anything is committed, as arguments and never through a shell. It must exit 0. A non-zero
exit refuses the bring-up, prints the script's line, removes the files that run wrote, and commits
nothing:
bash .aida/worktree-environment/preconditions.sh {codePath}
The script checks, in order, that the main checkout is a directory, that the line is not running in it, that uv is on the PATH, that the pyproject file and the lock file are there, and that the project-environment variable is unset. One line names the first failure and what to do about it.
Input contract
One token the consumer holds, and two the recipe produces:
{codePath}: string # the main checkout's path; the consumer fills it, in ## Preconditions
address: string # ## Address: the resolved path of the worktree's environment
root: string # ## Address: the directory holding it, which must be the worktree
No ## Tokens section: no command here needs a value read from the main checkout.
Sequence
-
Show. After
git worktree add, the consumer prints the## Preconditionsprose and the line it will run. -
Offer. The consumer prints the
## Bring upand## Tear downlines and the## Build in placeprose, and asks once. A no writes nothing, and the task record says so. An autonomous run takes the no. -
Write, check, commit. On a yes, the consumer writes the
## Fileswhere absent, then runs the## Preconditionsline with{codePath}filled. A non-zero exit refuses the bring-up, removes the files that run wrote, and commits nothing. On exit 0 it commits the files on the task's branch. -
Build. The consumer runs
## Bring upin the worktree. -
Record and confirm. The consumer runs
## Address, stops whenroot:is not the worktree, and recordsaddress:as the task's address. -
Tear down. When the task is pruned, the consumer runs
## Tear downin the worktree, thengit worktree remove.
Data flow
input: {codePath} held by the consumer
files (written where absent, committed after the check passes):
.aida/worktree-environment/preconditions.sh, address.sh, status.sh
preconditions (in the worktree, before the commit):
preconditions.sh {codePath} → exit 0, or one line naming the first failure
bring up (in the worktree):
uv sync --frozen → .venv, from uv.lock; the project installed editable
when it declares a [build-system]
address (in the worktree):
address.sh → address: <worktree>/.venv; root: <worktree>, checked
status (in the worktree):
status.sh → exit 0 when .venv/bin/python runs from <worktree>/.venv
tear down (in the worktree, before git worktree remove):
rm -rf .venv → the worktree's environment gone; files stay
State-awareness contract
uv sync --frozen can run twice: on an environment that already matches the lock file it changes
nothing, and on one that drifts it brings it back to the lock file. Running up again is how a
task refreshes its environment after the lock file changes on the branch.
A worktree that already holds a working .venv when up first runs is adopted, not synced: the
## Status line exits 0, so the consumer records the address and runs no precondition and no
bring-up line, and a later down lets go of the environment instead of removing it. For a full
bring-up, remove that .venv first.
Adoption is the likely path, not an edge case: uv run in the worktree creates .venv on its
own. Run up before any uv run, or remove .venv first. Prune refuses an adopted tree until a
person removes .venv and runs down again; that second down runs ## Status, which exits 1,
and the mark goes.
uv writes the environment inside .venv and no tracked file; the frozen sync never writes
uv.lock. A build backend that writes metadata into the source tree on an editable install, such
as setuptools' *.egg-info, leaves untracked files unless the project ignores them.
The three ## Files are written once, where absent, and committed on the task's branch once the
## Preconditions line has exited 0. Completion removes them again before the branch merges,
because they did not exist where the branch started.
## Tear down removes .venv and exits 0 when there is none, so a repeat run changes nothing.
Verifier
In the worktree, with uv on the PATH:
- Before bring-up,
bash .aida/worktree-environment/preconditions.sh <main checkout>prints nothing and exits 0. Run from the main checkout, with the uv project-environment variable set, with uv off the PATH, with a main checkout path that does not exist, or with nouv.lock, it prints one line saying which and exits 1. - Before bring-up,
bash .aida/worktree-environment/status.shprints that the environment is absent and exits 1. - After
uv sync --frozen,bash .aida/worktree-environment/address.shprintsaddress:, the worktree's.venv, androot:, the worktree;status.shexits 0. .venv/bin/pytestruns the suite, and, on a project with a[build-system],.venv/bin/python -c "import <package>; print(<package>.__file__)"prints a path inside the worktree.git status --shortin the worktree prints nothing, on a project that ignores__pycache__/and its build metadata. Step 4's import writes__pycache__/under the source tree.- After
## Tear down,status.shexits 1, and a second tear-down exits 0.
Status
One command, run before a consumer's verify lines.
bash .aida/worktree-environment/status.sh
Exit 0 means the worktree's own environment is there and its interpreter runs. A non-zero exit prints why.
Files
Three scripts in .aida/worktree-environment/, written where absent, the path as the fence's
second word. They hold every command that needs a quote or a substitution, so each line the
consumer runs stays plain arguments.
```sh .aida/worktree-environment/preconditions.sh
!/usr/bin/env bash
Checks what must be true before this worktree gets a Python environment. $1 is the main checkout.
One line names the first failure and exits 1; silence and exit 0 when everything holds.
main="$(cd "$1" 2>/dev/null && pwd -P)" || { echo "the main checkout $1 is not a directory"; exit 1; } here="$(pwd -P)" [ "$here" != "$main" ] || { echo "$here is the main checkout, not a task worktree; run this from the worktree"; exit 1; } command -v uv >/dev/null || { echo "uv is not on PATH; install it as https://docs.astral.sh/uv/getting-started/installation/ says"; exit 1; } [ -f pyproject.toml ] || { echo "no pyproject.toml in $here; this recipe is for a Python project uv manages"; exit 1; } [ -f uv.lock ] || { echo "no uv.lock in $here; run uv lock and commit uv.lock on the branch this worktree has checked out"; exit 1; } [ -z "${UV_PROJECT_ENVIRONMENT:-}" ] || { echo "UV_PROJECT_ENVIRONMENT is set to $UV_PROJECT_ENVIRONMENT, so uv would build the environment there and not in $here/.venv; unset it"; exit 1; }
```sh .aida/worktree-environment/address.sh
#!/usr/bin/env bash
# Prints the environment the worktree's .venv/bin/python runs in, as address:, and the directory
# holding it, as root:. Both are resolved, so a .venv that links to another checkout names that one.
prefix="$(.venv/bin/python -c 'import sys; print(sys.prefix)')" || exit 1
prefix="$(cd "$prefix" && pwd -P)" || exit 1
printf 'address: %s\nroot: %s\n' "$prefix" "$(dirname "$prefix")"
```sh .aida/worktree-environment/status.sh
!/usr/bin/env bash
Exits 0 when this worktree's own .venv holds a Python that runs; otherwise says why and exits 1.
here="$(pwd -P)" [ -x .venv/bin/python ] || { echo "no environment: $here/.venv/bin/python is absent"; exit 1; } prefix="$(.venv/bin/python -c 'import sys; print(sys.prefix)' 2>/dev/null)" || { echo "$here/.venv/bin/python does not run"; exit 1; } [ "$(cd "$prefix" 2>/dev/null && pwd -P)" = "$here/.venv" ] || { echo "$here/.venv runs from $prefix, not from this worktree"; exit 1; }
## Bring up
The consumer reads every fenced block tagged `sh` under `## Bring up`, one command per line, and
runs each as arguments from the worktree, never through a shell.
```sh
uv sync --frozen
It installs the default dependency groups, which include dev, where a uv project keeps pytest
and the review tools. A project that keeps them in another group declares it as a default group
in pyproject.toml.
Address
One command, run in the worktree. Its standard output is key: value lines:
bash .aida/worktree-environment/address.sh
Tear down
Run in the worktree, before git worktree remove:
rm -rf .venv
On a .venv that is a link, it removes the link and not what it points to.
Build in place
Every task on a Python command-line tool produces files on a branch, so none needs the main checkout's environment. A task that changes no Python code, such as one on documentation alone, has no use for an environment, and the person may decline the offer for it.
References
| Reference | Why |
|---|---|
uv: Project environments and uv sync |
--frozen installs from the lock file without checking or writing it; the environment is .venv in the project root |
| uv: Environment variables | UV_PROJECT_ENVIRONMENT moves the project environment out of .venv |
| uv: Dependency groups | dev is synced by default; default-groups changes which groups are |
python-cli/test-execution.md |
Resolves the runner as .venv/bin/pytest, which this environment provides |