# Worktrees The worktrees extension creates and tracks version-control checkouts for sessions and agents. Its [extension](../src/albedo/harness/extensions/worktrees/extension.gleam) registers host calls and managed context. [`worktree.gleam`](../src/albedo/harness/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`](../src/albedo/harness/worktree.gleam) and the [extension dispatch](../src/albedo/harness/extensions/worktrees/extension.gleam). ## Python The [Python binding](../priv/python/albedo_plugins/worktrees.py) 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](plugins.md#daemon-contributions) 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`](../src/albedo/harness/worktree.gleam) and the [extension instructions](../src/albedo/harness/extensions/worktrees/extension.gleam). ## 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](../src/albedo/harness/extensions/worktrees/extension.gleam) and [agents](agent-sessions.md). ## Managed context For a session associated with a worktree, the [extension](../src/albedo/harness/extensions/worktrees/extension.gleam) adds context naming the checkout and origin. Its context identifies the origin as the shared scope for memory and the work ledger. See [workspaces](workspaces.md) for locations and links. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Agents](agent-sessions.md) - [Files extension](files.md) - [Plugins](plugins.md)