autowt: a better git worktree experience
This README is generated from the index page of the docs. There are many more pages of docs at the link.
What are worktrees?
Worktrees are a built-in feature of git, which are essentially free clones of a local git repo. History is shared and synced across all worktrees for a given repo. Creating a new worktree is cheap, and you can list all your worktrees with a single command. This makes them a great fit for doing work “in parallel,” or not worrying about having uncommitted changes before working on another branch.
How autowt simplifies common workflows
While worktrees are powerful, the built-in tooling is minimalistic. Consider what it takes to set up a fresh worktree in a typical workflow:
- Make a decision about where to put the worktree
git worktree add <worktree_path> -b <branch>- Open a new terminal tab
cd <worktree path>uv syncornpm installor whatever your dependency setup iscp <repo_dir>/.env .to copy secrets
Congrats, you're done! Type type type, open a PR, and merge it. Now you need to clean up:
git worktree rm .- Close the tab
On the other hand, with autowt, it looks like this:
autowt <branch>
And deleting branches that have been merged or are associated with closed PRs looks like this:
autowt cleanup
A lot nicer, right?
Now suppose your team uses an issue tracker like Linear which can suggest branch names based on issue IDs. You could configure autowt to have a custom command to automatically open worktrees for tickets instead of passing a branch name:
autowt linear ABC-1234 # opens yourname/abc-1234-title-of-the-ticket or whatever
What autowt can do for you
- Worktree ergonomics: It's not hard to learn the commands to manage worktrees, but autowt shortens the most common ones. And autowt integrates with your terminal program to automate opening new sessions. It supports everything automate-terminal, including iTerm2, tmux, Ghostty, and more.
- Deep, customizable automation: You can define scripts in
.autowt.tomlto run at various points, like after creating a worktree but before switching to it, or before a worktree is cleaned up. Check out Lifecycle Hooks for more information. - Smart cleanup: You can configure autowt to automatically clean up worktrees whose branches have been merged, or even branches which are associated with closed pull requests on GitHub.
- Friendly TUIs: autowt uses interactive terminal-based UIs where it makes sense. For example,
autowt configgives you an easy way to edit global settings.autowt switchlets you review your worktrees and pick which one to navigate to.
Getting started
You'll need Python 3.10+ and a version of git released less than ten years ago (2.5+).
First, install autowt:
pip install autowt
Then, make a new worktree for a new or existing branch in your current repo:
autowt my-new-feature
Watch as autowt creates a new worktree and opens it in a new terminal tab or window.
Continue to full documentation
Contributing
PRs, GitHub issues, discussion topics, bring 'em on!
License
This project is licensed under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for autowt 0.5.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| autowt-0.5.5.tar.gz | 187.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| autowt-0.5.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 256.3 kB
Release files / autowt-0.5.5.tar.gz
| Download URL | autowt-0.5.5.tar.gz |
|---|---|
| Size | 187.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
458441bf70855656ba7a955fa55c26cd189798b82bc8818848ec73c4f22279ee
|
|
BLAKE2b-256 checksum How to use checksums |
35ff792e464a9a5e316f61ccaa78e2059e8241b803d9c35c58634cd779a87c13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 13, 2026.
Transparency logRelease files / autowt-0.5.5-py3-none-any.whl
| Download URL | autowt-0.5.5-py3-none-any.whl |
|---|---|
| Size | 68.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b17b1aed5847e91a72349a15b696cd65b9e7ebc9e47290325bf9b52c333e5ddb
|
|
BLAKE2b-256 checksum How to use checksums |
a3d05cbe76f28318c7f37790270142034be62769adc05809c348a0804040c2e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 13, 2026.
Transparency log
