Skip to content

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

docs: add FAQ entry for shell setup issues (#567)

Maximilian Roosca5b92be5a51
diff --git a/.claude-plugin/skills/worktrunk/reference/faq.md b/.claude-plugin/skills/worktrunk/reference/faq.md
index a9d1e9f8d..9b2dad080 100644
--- a/.claude-plugin/skills/worktrunk/reference/faq.md
+++ b/.claude-plugin/skills/worktrunk/reference/faq.md
@@ -131,6 +131,17 @@ $ cargo install worktrunk --no-default-features
This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
+## There's an issue with my shell setup
+
+If shell integration isn't working (auto-cd not happening, completions missing, `wt` not found as a function), the fastest path to a fix is using Claude Code with the Worktrunk plugin:
+
+1. Install the [Worktrunk plugin](https://worktrunk.dev/claude-code/) in Claude Code
+2. Ask Claude to debug the Worktrunk shell integration
+
+Claude will run `wt config show`, inspect your shell config files, and identify the issue.
+
+If Claude can't fix it, please [open an issue](https://github.com/max-sixty/worktrunk/issues/new?title=Shell%20setup%20issue&body=%23%23%20Shell%20and%20OS%0A%0A-%20Shell%3A%20%0A-%20OS%3A%20%0A%0A%23%23%20Output%20of%20%60wt%20config%20show%60%0A%0A%60%60%60%0A%0A%60%60%60%0A%0A%23%23%20What%20Claude%20found%20%28if%20available%29%0A%0A) with the output of `wt config show`, your shell (bash/zsh/fish), and OS. (And even if it fixes the problem, feel free to open an issue: non-standard success cases are useful for ensuring Worktrunk is easy to set up for others.)
+
## What files does Worktrunk create?
Worktrunk creates files in four categories.
diff --git a/docs/content/faq.md b/docs/content/faq.md
index d8d32c754..72338bf3a 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -141,6 +141,17 @@ $ cargo install worktrunk --no-default-features
This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
+## There's an issue with my shell setup
+
+If shell integration isn't working (auto-cd not happening, completions missing, `wt` not found as a function), the fastest path to a fix is using Claude Code with the Worktrunk plugin:
+
+1. Install the [Worktrunk plugin](@/claude-code.md) in Claude Code
+2. Ask Claude to debug the Worktrunk shell integration
+
+Claude will run `wt config show`, inspect your shell config files, and identify the issue.
+
+If Claude can't fix it, please [open an issue](https://github.com/max-sixty/worktrunk/issues/new?title=Shell%20setup%20issue&body=%23%23%20Shell%20and%20OS%0A%0A-%20Shell%3A%20%0A-%20OS%3A%20%0A%0A%23%23%20Output%20of%20%60wt%20config%20show%60%0A%0A%60%60%60%0A%0A%60%60%60%0A%0A%23%23%20What%20Claude%20found%20%28if%20available%29%0A%0A) with the output of `wt config show`, your shell (bash/zsh/fish), and OS. (And even if it fixes the problem, feel free to open an issue: non-standard success cases are useful for ensuring Worktrunk is easy to set up for others.)
+
## What files does Worktrunk create?
Worktrunk creates files in four categories.