[BUG] RTK Windows PowerShell Compatibility Gaps

Summary

RTK exposes several commands that appear generally available, but some of them are not compatible with a standard Windows PowerShell environment because RTK resolves real executables on PATH, not PowerShell aliases or shell built-ins. Windows setup behavior for rtk init -g is also surprising: in this environment it does not error, but it warns that hook-based mode requires Unix, falls back to --claude-md, and exits successfully. The user-reported rtk init -g --copilot repo-write behavior remains unverified in this pass.

Environment

• OS: Windows
• Shell: PowerShell
• Repository: TestBot3000
• RTK integration artifact present: .github/hooks/rtk-rewrite.json
• Copilot instructions file affected: .github/copilot-instructions.md

Full List Of PowerShell Counterpart Gaps

Based on the full rtk --help command surface plus direct PowerShell resolution checks in this environment, the complete currently identified set of commands or operations that fail for Windows PowerShell command-resolution reasons, while a Windows-native counterpart exists, is:

Additional scope notes:

• Get-Command in this environment reports ls, dir, and echo as aliases, not executables.
• Get-Command wc fails because there is no standard Windows wc executable.
• rtk find -name package.json succeeded in this environment, so find is not on this unsupported-counterpart list.

Verified In This Environment

rtk ls . fails on PowerShell

Repro:

rtk ls .

Observed behavior:

• RTK fails because it expects a real ls executable on PATH
• PowerShell's ls alias to Get-ChildItem is not treated as an executable

Expected behavior:

• RTK should either support a Windows-safe fallback or emit a targeted message explaining that PowerShell aliases are not supported and suggesting an alternative such as rtk tree .

rtk wc package.json fails on PowerShell

Repro:

rtk wc package.json

Observed behavior:

• RTK fails because wc is not a standard Windows executable on PATH

Expected behavior:

• RTK should either avoid advertising wc as generally usable on Windows or emit a Windows-specific fallback/help message

rtk discover fails without Claude history

Repro:

rtk discover

Observed behavior:

• RTK fails because it expects Claude Code history under ~/.claude/projects

Expected behavior:

• RTK should fail gracefully with a message that this command requires local Claude history and is not universally available

rtk session fails for the same missing-history assumption

Repro:

rtk session

Observed behavior:

• RTK fails because the same Claude history directory expectation is not met

Expected behavior:

• RTK should fail gracefully and document the prerequisite

rtk proxy only works with real executables

Repro:

rtk proxy dir
rtk proxy git status
rtk proxy echo hello

Observed behavior:

• rtk proxy dir fails because dir is a PowerShell alias, not an executable
• rtk proxy git status works
• rtk proxy echo hello fails because echo is a shell built-in, not an executable

Expected behavior:

• RTK should explicitly document that proxy requires real executables and does not resolve PowerShell aliases/built-ins

rtk curl https://example.com fails in this Windows environment

Repro:

rtk curl https://example.com

Observed behavior:

• RTK fails here due to Windows TLS or revocation behavior in the local environment
• This appears environment-sensitive and is weaker evidence than the ls and wc failures

Expected behavior:

• RTK docs should call out that curl behavior on Windows may depend on local TLS and certificate policy

rtk init -g falls back and succeeds on Windows

Repro:

rtk init -g

Exact output from the plain command:

[warn] Hook-based mode requires Unix (macOS/Linux).
	Windows: use --claude-md mode for full injection.
	Falling back to --claude-md mode.
[ok] C:\Users\username\.claude\CLAUDE.md already contains up-to-date rtk instructions

Observed behavior:

• The command does not prompt for input
• The command does not error
• A follow-up exit-code capture returned 0
• RTK reports a Windows-specific fallback from hook-based mode to --claude-md
• No additional repo-local writes were observed in this run
• .github/copilot-instructions.md and .github/hooks/rtk-rewrite.json kept the same size and LastWriteTime before and after the run
• The repository changed-file set did not gain any new repo-local entries after the run

Expected behavior:

• If this Windows fallback is intentional, RTK should document rtk init -g as a successful --claude-md fallback instead of implying hook installation works everywhere
• If this fallback is not intended, RTK should make the scope change explicit before continuing

User-Reported But Not Re-Run In This Turn

rtk init -g --copilot installs locally and overwrites repo files

Observed by user:

• rtk init -g --copilot succeeds
• It installs repo-local artifacts instead of behaving like a pure global install
• It overwrites .github/copilot-instructions.md

Why this is surprising:

• --global implies user-wide setup
• --copilot currently appears able to write repository-scoped integration files even when --global is present

Expected behavior:

• rtk init -g should remain global-only
• If --copilot requires repo-local writes, RTK should either reject the flag combination or state clearly that --copilot changes scope to repository-local integration

Suspected Root Causes

1. RTK resolves native executables on PATH and does not understand PowerShell aliases or built-ins.
2. The concrete counterpart-gap cases identified here are ls, dir, echo, and wc.
3. Some meta commands assume local Claude session history exists.
4. rtk init Windows semantics are underdocumented, especially the --global fallback to --claude-md and the unclear --global plus --copilot interaction.

Expected Behavior

• Commands presented as generally available should either work in standard PowerShell or clearly declare their Windows limitations.
• RTK should differentiate between executable resolution and PowerShell alias resolution in its error messages.
• Windows-incompatible commands should offer actionable fallback suggestions.
• rtk init -g should clearly document its Windows fallback behavior.
• --global should not silently lead to repo-local writes when combined with --copilot.

Actual Behavior

• PowerShell aliases like ls are treated as missing commands.
• PowerShell aliases like dir and echo also fail when routed through rtk proxy.
• Unix-only tools like wc fail without a Windows-aware fallback.
• discover and session fail when local Claude history is absent.
• On Windows, rtk init -g warns, falls back to --claude-md, and exits 0 without changing repo-local files in this run.
• The user-reported global Copilot install path is still confusing because --copilot may be able to write repo-local files.

Suggested Fixes

1. Add Windows-aware fallback messages for commands like ls and wc.
2. Document that PowerShell aliases and built-ins are not equivalent to executables for RTK command resolution.
3. Clearly mark discover and session as conditional commands that require local Claude history.
4. Document that rtk init -g falls back to --claude-md on Windows.
5. Clarify or change rtk init semantics so --global and --copilot cannot produce surprising repo-local writes.
6. If mixed global/local behavior is intentional, print an explicit warning before modifying repository files.

Minimal Repro Set

rtk ls .
rtk wc package.json
rtk proxy dir
rtk proxy echo hello
rtk discover
rtk session
rtk curl https://example.com
rtk init -g

Running commands outputs the hook warning

PS C:\Source\TestBot3000> rtk git log -10
[rtk] /!\ No hook installed — run `rtk init -g` for automatic token savings
53577ba ver update (12 hours ago) <username>
c5295bb feat(renderer): add updates rail for desktop updates (#40) (12 hours ago) <username>
  Move the shared desktop update surface into a dedicated
  Updates rail panel and keep Debug focused on diagnostics.
  Hide the titlebar update control unless an update can be
  [+2 lines omitted]
5669b93 feat(installer): implement Velopack update URL persistence for packaged Windows installs (21 hours ago) <username>
d5bd609 fix(desktop): correct runtime wiring for installed builds (#39) (21 hours ago) <username>
  Bridge explicit source, packaged, and installed runtime metadata\nfrom the Electron main process into the renderer so...
6a98b21 fix(desktop): expand update monitoring and release wiring (#32) (24 hours ago) <username>
74718cc chore(release): bump version to 0.1.1 (3 days ago) <username>
.........