Worktree Controller

Worktree Controller (WC) helps people and AI agents share a Git repository without losing track of who owns each working directory, what it may change, and whether it is safe to close. It checks repository policy before allocating a worktree, grants writing authority to a live process, and records handoff, integration, recovery and release evidence. Git remains the source of truth for files, branches, commits and registered worktrees.

Current release: 1.30.5 · Linux · Python 3.12 · Apache-2.0

Install

Use a virtual environment in a new directory:

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install worktree-controller==1.30.5
worktree-controller --version
worktree-controller capabilities --json

WC requires Git and readable Linux /proc. Other operating systems and Python versions are not supported by this release. Its one runtime dependency is websockets>=15,<16. Software version 1.30.5 retains CLI contract 60 and storage layout 5.

Try it in a disposable repository

With the environment above active:

git clone https://github.com/xuanheng-tech/worktree-controller.git wc
cd wc
git checkout v1.30.5
python examples/quickstart.py --workspace "$HOME/wc-first-run"

The workspace path must not exist; its parent must already exist. The example creates its own repository and isolated HOME, uses no credentials or remote, and leaves existing projects alone. It runs a small inspection task: admit a worktree, bind a live writer, check permission, observe an expected wrong-owner refusal, inspect recovery guidance, and formally close the unchanged task. On success it prints PASS, releases the linked checkout through WC, and keeps the repository, branch and command log. On failure it stops and preserves results for inspection.

The getting started guide explains the output and how to proceed to tasks that change files. The example also ships in the source distribution; it requires only WC and Git, with no companion delivery tools.

Use WC in a real project

A governed repository tracks .agents/worktree-policy.toml and registers its checkouts with WC. Start with read-only status and doctor; adopt existing checkouts explicitly rather than assuming that a clean directory is unowned. Follow the operations guide for task admission, writer identity, handoff, integration and safe release.

WC manages checkout authority and lifecycle. It does not implement your task, commit changes or publish a branch. Real handoff and integration flows use separate delivery evidence from Git Finalizer. Context Loader and Snapshot Runner are optional companion tools; see optional integrations.

When blocked, run worktree-controller recovery-guide --repo /path/to/repo --path /path/to/checkout --json and follow the state-specific guidance. Preserve unfinished changes and unknown files. At session end, use the full recorded session identity and check every allocation's result; a successful process exit alone does not prove that all worktrees are settled.

Documentation and help

• Getting started
• Operations and recovery
• Technical reference
• Architecture
• Exact CLI and capability contract
• Changelog
• Releases · PyPI
• Report a bug · Contribute
• Report a security issue

Licensed under the Apache License 2.0.