Worktrees #
The worktrees extension creates and tracks version-control checkouts for
sessions and agents. Its
extension
registers host calls and managed context.
worktree.gleam owns the common record
and lifecycle.
Layout #
worktree.base_dir places managed checkouts under $ALBEDO_HOME/wt.
worktree_path adds a repository slug and a chosen name. The record
distinguishes the checkout path from workspace, which preserves the origin's
subdirectory within the checkout. origin records the originating workspace.
Creation rejects remote SSH locations.
Worktree providers #
A worktree.Provider detects a repository and implements creation, listing, and
removal for its version-control system. worktree.detect selects a matching
enabled provider. worktree.create creates the checkout and records it. If
recording fails, it attempts to remove the checkout. The extension can select a
provider by kind. See worktree.gleam
and the
extension dispatch.
Python #
The Python binding exposes
asynchronous worktrees.create, get, query, list, and remove. A
Worktree record includes its ID, repository, workspace, kind, revision,
branch, session, and existence state. query supports filters. list returns
the matching records.
worktree.remove refuses the main checkout and paths outside the managed base.
Without force, it refuses a worktree occupied by a running session. Removal
deletes the checkout, then runs every declared extension's WorktreeRemoved
follower in the transaction that deletes the
record. Route callers pass context.followers. The work extension's follower
moves work-ledger entries to the origin checkout. Closing an agent does not
automatically delete its worktree. See
remove and the
extension instructions.
Agents #
The extension accepts a worktree for agent creation, or a request to create one for the agent. The agent's workspace then points into that checkout. See the worktrees extension and agents.
Managed context #
For a session associated with a worktree, the extension adds context naming the checkout and origin. Its context identifies the origin as the shared scope for memory and the work ledger. See workspaces for locations and links.