kwt documentation¶
kwt is a Git worktree manager for people and coding agents. It creates one isolated checkout per branch, opens a tmux workspace in it, shows the state of every worktree across registered projects, and removes worktrees safely.
This site documents the commands, JSON contracts, configuration, and design of kwt. The product overview and the guide are the shorter introductions.
Requirements¶
- macOS 13 or newer, Linux, or Windows.
- Git 2.20 or newer.
kwt doctorandkwt prunerequire Git 2.31 or newer;kwt pr importrequires Git 2.42.0 or newer on macOS and Linux, or Git for Windows 2.53.0.windows.3 or newer. - tmux 2.1 or newer for workspace launch and
kwt tmux. The worktree commands work without tmux. - Go 1.27 or newer for
go installand source builds.
See Install for every install path and Releases for versioning.
Where to start¶
| Goal | Page |
|---|---|
| Create and open a first worktree interactively | Quickstart |
| Drive worktrees from an agent or script | Agent workspaces |
| Inspect, diagnose, prune, and remove worktrees | Worktree lifecycle |
| Manage tmux workspaces for non-Git directories | Directory workspaces |
| Import a pull request into an isolated checkout | Pull-request automation |
| Compare worktree state across machines | Multi-machine sync |
| Embed kwt in a Go application or terminal client | Embed and connect kwt |
Contracts¶
| Contract | Page |
|---|---|
| Commands, JSON fields, exit status, guarded flags | CLI reference |
config.toml, .kwt.toml trust, layouts, agents |
Configuration |
| Trusted local state versus untrusted branch data | Threat model |
| Architecture behind each boundary | Design notes |
| Release history | Changelog |
State and configuration¶
Global configuration lives at ~/.config/kwt/config.toml, or
$KWT_HOME/config.toml when KWT_HOME is set. KWT_HOME also holds
registry.json and pull-requests.json, so it isolates kwt's persistent state
as a unit. Repository-local .kwt.toml settings are trust-gated before use.
Safety boundaries¶
Worktrees created from existing local or remote branches start inert: kwt does
not run repository setup, copy configured files, or launch a workspace until
you review the checkout and open it explicitly. Pull-request imports use a
protected session boundary and preserve exact push routing. Removal refuses
dirty worktrees and worktrees in use by a live process unless --force is
given. Multi-machine sync is opt-in and reports advisory state only.
For agents¶
Every page on this site is also served as Markdown at the same path with a
.md suffix, for example https://kwt.sh/docs/reference/cli.md, and each rendered
page advertises it with a rel="alternate" link. /llms.txt
indexes the product, guide, and documentation pages. Machine-readable command
output is documented in the CLI reference.