This release is a pre-release and may not be stable for production use.
Worktree (wt)
Isolated git worktree developer loops and autonomous AI agent workspaces.
Worktree helps humans and agents build, test, and remediate in parallel without disturbing your active local branch.
Installation
pip install getworktree
Optional provider extras:
pip install "getworktree[cursor]"
Requirements
- Python 3.13+
- Git
- For provider-specific loop runs:
- Cursor:
CURSOR_API_KEY(+getworktree[cursor]) - Gemini: Gemini CLI on
PATH+GEMINI_API_KEY - Copilot: GitHub CLI (
gh) onPATH+GH_TOKENorGITHUB_TOKEN
- Cursor:
Quick start
wt init
wt status
wt config validate
wt workflow list
wt workflow show wf-12345
wt workflow run fix-tests
Current command surface
Top-level
wt initwt status
Config
wt config showwt config validate
Workflow
wt workflow list(orwt workflow)wt workflow show <id>wt workflow run <name>wt workflow resume <id>
Agent providers for loop runs
Loop definitions support these providers:
localollamacursorgeminicopilot
Provider behavior:
localandollamareturn unified diffscursor,gemini, andcopilotrun as direct-mutation providers with shared safety gates before patches are accepted
Project layout
Worktree initializes and uses:
.worktree/config.json.worktree/loops/*.yml.worktree/sessions/.worktree/artifacts/
Development
pip install -e .[dev]
inv test
ruff format .
ruff check .
Documentation
- CLI plan: docs/cli-plan.md
- Schemas and config: docs/agents/schemas-and-config.md
- Architecture: docs/agents/architecture.md
Project status
This README reflects the currently implemented surface in main.
Additional commands listed in docs/cli-plan.md may still be in progress.
License
Distributed under the MIT License. See LICENSE for details.
Links
- Website: getworktree.io
- GitHub Organization: github.com/getworktree
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file getworktree-0.1.1.dev75.tar.gz.
File metadata
- Download URL: getworktree-0.1.1.dev75.tar.gz
- Upload date:
- Size: 14.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eabdfed2dad3c46cc71f3fdae86adc1d1ab6f4e4deec0c9be8ef93707eba9791
|
|
| MD5 |
22393e0d25dbf7200558e7ee8bed3ee5
|
|
| BLAKE2b-256 |
e152d68c3b9ade3f30b4c50ec611712ef32212784927845c6aba26d0be46adcd
|
Provenance
The following attestation bundles were made for getworktree-0.1.1.dev75.tar.gz:
Publisher:
dev-publish.yml on getworktree/getworktree
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
getworktree-0.1.1.dev75.tar.gz -
Subject digest:
eabdfed2dad3c46cc71f3fdae86adc1d1ab6f4e4deec0c9be8ef93707eba9791 - Sigstore transparency entry: 2350794846
- Sigstore integration time:
-
Permalink:
getworktree/getworktree@1b67c0658b955bc5326c85ba9cd67e0a222cdf8c -
Branch / Tag:
refs/heads/main - Owner: https://github.com/getworktree
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
dev-publish.yml@1b67c0658b955bc5326c85ba9cd67e0a222cdf8c -
Trigger Event:
push
-
Statement type:
File details
Details for the file getworktree-0.1.1.dev75-py3-none-any.whl.
File metadata
- Download URL: getworktree-0.1.1.dev75-py3-none-any.whl
- Upload date:
- Size: 13.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9e13c48011aef222ad2621b3216eb3d8effa8ece3c6d0a4f3a1a4e5dc3e28137
|
|
| MD5 |
55e166f8ded92c6774ab5b3e4f4cf6c3
|
|
| BLAKE2b-256 |
bbef8ea6257485eb06a2d4c8dc02ddf91fff2c3410ec1f7d4ab8249ba6b3e2a3
|
Provenance
The following attestation bundles were made for getworktree-0.1.1.dev75-py3-none-any.whl:
Publisher:
dev-publish.yml on getworktree/getworktree
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
getworktree-0.1.1.dev75-py3-none-any.whl -
Subject digest:
9e13c48011aef222ad2621b3216eb3d8effa8ece3c6d0a4f3a1a4e5dc3e28137 - Sigstore transparency entry: 2350795665
- Sigstore integration time:
-
Permalink:
getworktree/getworktree@1b67c0658b955bc5326c85ba9cd67e0a222cdf8c -
Branch / Tag:
refs/heads/main - Owner: https://github.com/getworktree
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
dev-publish.yml@1b67c0658b955bc5326c85ba9cd67e0a222cdf8c -
Trigger Event:
push
-
Statement type:
