kwt is a Git worktree manager with a terminal dashboard for people and a
scriptable CLI for agents and other tools. It creates isolated checkouts, opens
their tmux workspaces, shows their current state, and cleans them up safely
across all your projects.
Run kwt inside a repository to register the project and open the dashboard:
kwtThe dashboard shows known projects and worktrees in one place. Create a branch
and worktree with n, search existing branches with b, attach to the selected
workspace with enter, and remove a worktree with d.
See the quickstart for the complete first-use path. Ordinary directories can also become directory workspaces.
Agents and other tools can use plain commands and stable JSON for the same lifecycle:
kwt add -b feature/new-ui
kwt exec feature/new-ui -- make test
kwt changes --json
kwt remove -b feature/new-uiUse agent workspaces for a complete automation loop, pull-request automation for inert imports and protected attachment, and the CLI reference for commands and machine contracts.
Install the current release with Go:
go install go.kenn.io/kwt/cmd/kwt@v0.5.0Prebuilt macOS, Linux, and Windows archives and checksums are available from GitHub Releases. See the installation guide for archive and source-build instructions.
Requirements:
- Git 2.20 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.kwt doctor,kwt prune --expired, andkwt prune --mergedrequire Git 2.31 or newer. - tmux 2.1 or newer for workspace launch and
kwt tmux. - Go 1.27 or newer when installing or building from source.
- macOS 13 or newer, Linux, or Windows.
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. Multi-machine sync is opt-in and reports advisory state; follow the multi-machine guide before enabling it.
Ghosthub bundles kwt to manage project registration, linked worktrees, pull-request imports, and tmux workspaces across local and SSH-hosted machines. Ghosthub is one consumer of the same services available to other kwt clients and embedders.
Applications can construct kwt's transport-neutral inventory, removal, and generation-safe change-inspection services directly:
import kwt "go.kenn.io/kwt"
inventory := kwt.NewInventoryService(kwt.InventoryServiceOptions{Source: source})
removals := kwt.NewRemovalService(kwt.RemovalServiceOptions{Home: kwtHome})
inspections := kwt.NewInspectionService(kwt.InspectionServiceOptions{
Inventory: inventory,
})The CLI and terminal dashboard use the same core services through kwt's local daemon. The package documentation contains the public Go API. See Embed and connect kwt to choose between direct Go services, the local daemon or CLI, and a tmux session endpoint.
Global configuration lives at ~/.config/kwt/config.toml, or
$KWT_HOME/config.toml when KWT_HOME is set. Repository-local .kwt.toml
settings are trust-gated before use. KWT_HOME also holds registry.json and
pull-requests.json, so it isolates kwt's persistent state as a unit.
The configuration reference covers worktree paths, layouts, agents, repository setup, trust, daemon and SSH policy, and optional multi-machine settings.
The maintained documentation lives at kwt.sh. Start with:
kwt uses semantic-version tags. Pushing a vMAJOR.MINOR.PATCH tag runs the test
suite and publishes platform archives plus checksums. See the
release checklist for the maintainer workflow.
To build the documentation locally:
make docs-install
make docs-build
make docs-serveApache-2.0. See LICENSE and NOTICE.1