docs: add Windows hook wiring guide (fix silent hook failures) - #660
Conversation
Document why TeamAI hooks silently fail on Windows (bare bash -> WSL Node 18 crash; hasShell() /bin/sh check skips codebuddy/workbuddy) and provide a durable user-side fix (Git Bash absolute path + WSL wrapper). Include a suggested upstream fix for maintainers. Bilingual (en + zh-CN) to match repo docs convention.
|
Summary
On Windows the hooks TeamAI injects are silently dead, so the team's shared
rules/skills and session stats never reach CodeBuddy / Qoder / WorkBuddy, and
even the "working" tools don't actually fire. This PR adds a bilingual guide
(
docs/windows-hooks.md+docs/windows-hooks.zh-CN.md, matching the repo'sexisting
usage-guide/ci-code-erosionconvention) explaining the cause anda durable user-side fix, plus a concrete suggested upstream fix.
The problem
bash→ WSL Node 18 crash. The injected hook command isbash -lc "teamai hook-dispatch ..." || true. On Windowsbashresolves tothe WSL launcher (
C:\Windows\System32\bash.exe), whose bundled Node is v18and can't parse the TeamAI bundle. The crash is swallowed by
|| true, soteamai doctorstill reports the hooks as "present" while they never run.hasShell()skips CodeBuddy / WorkBuddy.src/builtin-hooks.tsgates
SHELL_DEPENDENT_TOOLSonfs.existsSync('/bin/sh'), which is alwaysfalseon Windows. As a result those two agents get no hooks injected atall (WorkBuddy has a partial escape hatch via its bundled PortableGit
sh.exe, butcodebuddyis skipped unconditionally).What this PR adds
A community guide covering:
agent settings file and (B) a WSL wrapper that delegates to native Windows
teamaiviacmd.exeso hooks survive a laterteamai pull.teamai doctor+ per-toolhook-dispatchreturningexit=0through both mechanisms).
Suggested upstream fix (for maintainers)
Two small, backward-compatible changes would make Windows work out of the box —
described in detail in the doc:
hasShell()Windows-aware (detect Git for Windowssh.exe/bash.exeor WSL
bashinstead of always returningfalse), socodebuddy/workbuddyhooks get injected.getDispatchCommand()to the Git Bash absolute path (or bundledPortableGit
sh.exe) whenprocess.platform === 'win32', avoiding the WSLNode 18 crash.
This PR is docs-only; I left the source untouched so maintainers can apply
the suggested fix in the way that best fits the codebase (and its existing
bundledShellFor/hasShellFordesign).Verification
Guide verified locally:
teamai doctor✔ for claude, codex, qoder, zcode,codebuddy, workbuddy; every
hook-dispatchreturnsexit=0via both the GitBash path and the bare-
bash-via-WSL mechanisms.