Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: add Windows install guidance to README (#661)

Maximilian Roosf1b525c5df8b
diff --git a/.claude-plugin/skills/worktrunk/reference/faq.md b/.claude-plugin/skills/worktrunk/reference/faq.md
index 3bf7ee5c0..ae474bde2 100644
--- a/.claude-plugin/skills/worktrunk/reference/faq.md
+++ b/.claude-plugin/skills/worktrunk/reference/faq.md
@@ -86,23 +86,6 @@ If the remote's default branch has changed (e.g., renamed from master to main),
For full details on the detection mechanism, see `wt config state default-branch --help`.
-## On Windows, `wt` conflicts with Windows Terminal
-
-Windows Terminal uses `wt` as its command-line launcher, so running `wt` invokes Terminal instead of Worktrunk.
-
-As an immediate workaround, install as `git-wt`:
-
-```bash
-cargo install worktrunk --features git-wt
-git-wt config shell install
-```
-
-This creates a `git-wt` shell function with directory changing and completions.
-
-`git wt` (as a git subcommand) also works but cannot change directories since git runs subcommands as subprocesses.
-
-We're considering better solutions — a better name, anyone?
-
## Does Worktrunk work on Windows?
**Experimental.** Core functionality works, but some features are unavailable.
diff --git a/.claude-plugin/skills/worktrunk/reference/worktrunk.md b/.claude-plugin/skills/worktrunk/reference/worktrunk.md
index ee2ee3648..e40a2fdee 100644
--- a/.claude-plugin/skills/worktrunk/reference/worktrunk.md
+++ b/.claude-plugin/skills/worktrunk/reference/worktrunk.md
@@ -91,6 +91,20 @@ Shell integration allows commands to change directories.
cargo install worktrunk && wt config shell install
```
+<details>
+<summary><strong>Windows</strong></summary>
+
+On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
+
+```bash
+winget install max-sixty.worktrunk
+git-wt config shell install
+```
+
+Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
+
+</details>
+
## Next steps
- Learn the core commands: [`wt switch`](https://worktrunk.dev/switch/), [`wt list`](https://worktrunk.dev/list/), [`wt merge`](https://worktrunk.dev/merge/), [`wt remove`](https://worktrunk.dev/remove/)
diff --git a/README.md b/README.md
index c5e33f093..2fce14cb4 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,20 @@ Shell integration allows commands to change directories.
cargo install worktrunk && wt config shell install
```
+<details>
+<summary><strong>Windows</strong></summary>
+
+On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
+
+```bash
+winget install max-sixty.worktrunk
+git-wt config shell install
+```
+
+Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
+
+</details>
+
## Next steps
- Learn the core commands: [`wt switch`](https://worktrunk.dev/switch/), [`wt list`](https://worktrunk.dev/list/), [`wt merge`](https://worktrunk.dev/merge/), [`wt remove`](https://worktrunk.dev/remove/)
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 6330fc4b8..759c9b87c 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -96,23 +96,6 @@ If the remote's default branch has changed (e.g., renamed from master to main),
For full details on the detection mechanism, see `wt config state default-branch --help`.
-## On Windows, `wt` conflicts with Windows Terminal
-
-Windows Terminal uses `wt` as its command-line launcher, so running `wt` invokes Terminal instead of Worktrunk.
-
-As an immediate workaround, install as `git-wt`:
-
-```bash
-cargo install worktrunk --features git-wt
-git-wt config shell install
-```
-
-This creates a `git-wt` shell function with directory changing and completions.
-
-`git wt` (as a git subcommand) also works but cannot change directories since git runs subcommands as subprocesses.
-
-We're considering better solutions — a better name, anyone?
-
## Does Worktrunk work on Windows?
**Experimental.** Core functionality works, but some features are unavailable.
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 36c019af7..03c139f95 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -110,6 +110,20 @@ Shell integration allows commands to change directories.
cargo install worktrunk && wt config shell install
```
+<details>
+<summary><strong>Windows</strong></summary>
+
+On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
+
+```bash
+winget install max-sixty.worktrunk
+git-wt config shell install
+```
+
+Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
+
+</details>
+
## Next steps
- Learn the core commands: [`wt switch`](@/switch.md), [`wt list`](@/list.md), [`wt merge`](@/merge.md), [`wt remove`](@/remove.md)