Merge pull request #36 from alex-feel/alex-feel-dev

Implement working PowerShell/CMD wrappers for claude-python command

Author: alex-feel

README.md

@@ -36,11 +36,12 @@ This automated setup includes:
 - 🔧 Comprehensive Python developer system prompt
 - 🚀 Convenience launchers for quick startup
 
-**⚠️ IMPORTANT: After setup, use the simple command:**
+**✅ After setup, use the simple command:**
 ```bash
-claude-python
+claude-python  # Works in all Windows shells (PowerShell, CMD, Git Bash)
 ```
-That's it! The setup script registers this command globally.
+
+The setup automatically creates properly escaped wrappers for each Windows shell, ensuring the Python developer system prompt loads correctly regardless of which shell you use.
 
 ---
 
@@ -205,12 +206,14 @@ After running the Python setup script:
 claude doctor
 
 # 2. Start Claude with Python configuration - just run:
-claude-python
+claude-python  # Windows: Git Bash ONLY!
 
 # That's it! The command is registered globally during setup
 ```
 
-**⚠️ Common Mistake:** Running `claude` directly won't load the Python system prompt! Always use `claude-python` command.
+**⚠️ Common Mistakes:**
+- Running `claude` directly won't load the Python system prompt!
+- On Windows: `claude-python` ONLY works in Git Bash, NOT in PowerShell or CMD!
 
 For IDE integration:
 - **VS Code**: Configure terminal to use the launcher script

scripts/README.md

@@ -126,7 +126,7 @@ Complete Python development environment that installs:
   - /test (test generation)
 - **Python developer system prompt** with SOLID, DRY, KISS, YAGNI principles
 - **Context7 MCP server** for up-to-date library documentation
-- **Global `claude-python` command** that works in all terminals (PowerShell, CMD, Git Bash)
+- **Global `claude-python` command** (works in PowerShell, CMD, and Git Bash on Windows)
 
 ## 🔧 Script Options
 
@@ -193,8 +193,8 @@ chmod +x setup-python-environment.sh
 - **Python Version**: Requires Python 3.12+ (automatically handled by uv)
 - **Package Manager**: Uses uv for fast, reliable Python management
 - **Windows**: PowerShell 5.1+ for bootstrap, full Windows 10/11 support
-  - `claude-python` command works in PowerShell, CMD, and Git Bash
-  - Automatic creation of both .cmd and bash wrappers
+  - `claude-python` command works in **all Windows shells** (PowerShell, CMD, Git Bash)
+  - Automated wrappers handle shell-specific escaping requirements
 - **Linux**: Bash 4.0+ for bootstrap, tested on Ubuntu, Debian, Fedora, Arch
 - **macOS**: Compatible with macOS 10.15+ (Catalina and later)
 
@@ -205,10 +205,9 @@ chmod +x setup-python-environment.sh
 - **Intelligent Path Management**: Automatic PATH configuration
 - **Git Bash Detection**: Multiple detection strategies on Windows
 - **Node.js Management**: Automatic LTS installation if needed
-- **Cross-Terminal Support**: Windows commands work in all terminal types
-  - Creates both .cmd files for PowerShell/CMD
-  - Creates bash wrappers for Git Bash compatibility
-  - Single `claude-python` command works everywhere
+- **Cross-Shell Support on Windows**: Automated wrappers for all shells
+  - `claude-python` command works in PowerShell, CMD, and Git Bash
+  - Each shell has a properly escaped wrapper for reliable operation
 
 ### Error Handling
 

scripts/setup-python-environment.py

@@ -330,7 +330,7 @@ def create_launcher_script(claude_user_dir: Path) -> Path | None:
 
     try:
         if system == 'Windows':
-            # PowerShell launcher
+            # Create PowerShell launcher for Windows
             launcher_path = launcher_path.with_suffix('.ps1')
             launcher_content = '''# Claude Code Python Environment Launcher
 # This script starts Claude Code with the Python developer system prompt
@@ -346,51 +346,64 @@ def create_launcher_script(claude_user_dir: Path) -> Path | None:
 
 Write-Host "Starting Claude Code with Python developer configuration..." -ForegroundColor Green
 
-# Find Git Bash (it's required for Claude Code on Windows)
+# Find Git Bash (required for Claude Code on Windows)
 $bashPath = $null
-if ($env:CLAUDE_CODE_GIT_BASH_PATH) {
-    $bashPath = $env:CLAUDE_CODE_GIT_BASH_PATH
-} elseif (Test-Path "C:\\Program Files\\Git\\bin\\bash.exe") {
+if (Test-Path "C:\\Program Files\\Git\\bin\\bash.exe") {
     $bashPath = "C:\\Program Files\\Git\\bin\\bash.exe"
 } elseif (Test-Path "C:\\Program Files (x86)\\Git\\bin\\bash.exe") {
     $bashPath = "C:\\Program Files (x86)\\Git\\bin\\bash.exe"
 } else {
-    $bashCmd = Get-Command bash -ErrorAction SilentlyContinue
-    if ($bashCmd) {
-        $bashPath = $bashCmd.Source
-    }
-}
-
-if (-not $bashPath) {
     Write-Host "Error: Git Bash not found! Please install Git for Windows." -ForegroundColor Red
     exit 1
 }
 
-# Convert Windows path to Unix path for bash
-$unixPromptPath = $promptPath -replace '\\\\', '/' -replace 'C:', '/c'
-
-# Build the bash command with proper escaping
-# The inner quotes need to be escaped for bash -c
-$bashCommand = "claude --append-system-prompt \\`"\\$`(cat '$unixPromptPath'`)\\`""
+# Build the bash command with all arguments
 if ($args.Count -gt 0) {
     Write-Host "Passing additional arguments: $args" -ForegroundColor Cyan
-    $bashCommand += " " + ($args -join " ")
+    # When we have arguments, we can't use --% so we escape properly
+    $argsString = ($args -join ' ')
+    $bashCmd = "p=`$(tr -d '\\\\r' < ~/.claude/prompts/python-developer.md); "
+    $bashCmd += "exec claude --append-system-prompt=\\`"`$p\\`" $argsString"
+    $bashCommand = $bashCmd
+    & $bashPath -lc $bashCommand
+} else {
+    $cmd = "p=$(tr -d '\\\\r' < ~/.claude/prompts/python-developer.md); "
+    $cmd += "exec claude --append-system-prompt=\"$p\""
+    & $bashPath --% -lc "$cmd"
 }
-
-Write-Host "Executing command via Git Bash..." -ForegroundColor Yellow
-
-# Execute via Git Bash
-& $bashPath -c $bashCommand
 '''
             launcher_path.write_text(launcher_content)
 
-            # Also create a batch file wrapper
+            # Also create a CMD batch file wrapper
             batch_path = claude_user_dir / 'start-python-claude.cmd'
-            batch_content = f'@echo off\npowershell -NoProfile -ExecutionPolicy Bypass -File "{launcher_path}" %*'
+            batch_content = '''@echo off
+REM Claude Code Python Environment Launcher for CMD
+REM This script starts Claude Code with the Python developer system prompt
+
+set PROMPT_PATH=%USERPROFILE%\\.claude\\prompts\\python-developer.md
+
+if not exist "%PROMPT_PATH%" (
+    echo Error: Python developer prompt not found at %PROMPT_PATH%
+    echo Please run setup-python-environment.py first
+    exit /b 1
+)
+
+echo Starting Claude Code with Python developer configuration...
+
+REM Build the command with all arguments
+set BASH_EXE="C:\\Program Files\\Git\\bin\\bash.exe"
+set CMD_PREFIX=p=$(tr -d '\\r' ^< ~/.claude/prompts/python-developer.md)
+if "%~1"=="" (
+    %BASH_EXE% -lc "%CMD_PREFIX%; exec claude --append-system-prompt=\\"$p\\""
+) else (
+    echo Passing additional arguments: %*
+    %BASH_EXE% -lc "%CMD_PREFIX%; exec claude --append-system-prompt=\\"$p\\" %*"
+)
+'''
             batch_path.write_text(batch_content)
 
         else:
-            # Bash launcher
+            # Create bash launcher for Unix-like systems
             launcher_path = launcher_path.with_suffix('.sh')
             launcher_content = '''#!/usr/bin/env bash
 # Claude Code Python Environment Launcher
@@ -441,11 +454,29 @@ def register_global_command(launcher_path: Path) -> bool:
             local_bin = Path.home() / '.local' / 'bin'
             local_bin.mkdir(parents=True, exist_ok=True)
 
+            # Create wrappers for all Windows shells
+            # CMD wrapper
             batch_path = local_bin / 'claude-python.cmd'
-            batch_content = f'@echo off\npowershell -NoProfile -ExecutionPolicy Bypass -File "{launcher_path}" %*'
+            batch_content = '''@echo off
+REM Global claude-python command for CMD
+set BASH_EXE="C:\\Program Files\\Git\\bin\\bash.exe"
+set CMD_PREFIX=p=$(tr -d '\\r' ^< ~/.claude/prompts/python-developer.md)
+if "%~1"=="" (
+    %BASH_EXE% -lc "%CMD_PREFIX%; exec claude --append-system-prompt=\\"$p\\""
+) else (
+    %BASH_EXE% -lc "%CMD_PREFIX%; exec claude --append-system-prompt=\\"$p\\" %*"
+)
+'''
             batch_path.write_text(batch_content)
 
-            # Also create a bash wrapper for Git Bash compatibility
+            # PowerShell wrapper (as a simple forwarder to the PS1 launcher)
+            ps1_wrapper_path = local_bin / 'claude-python.ps1'
+            ps1_wrapper_content = f'''# Global claude-python command for PowerShell
+& "{launcher_path}" @args
+'''
+            ps1_wrapper_path.write_text(ps1_wrapper_content)
+
+            # Git Bash wrapper
             bash_wrapper_path = local_bin / 'claude-python'
             bash_content = '''#!/bin/bash
 # Bash wrapper for claude-python to work in Git Bash
@@ -476,7 +507,7 @@ def register_global_command(launcher_path: Path) -> bool:
             # Make it executable (Git Bash respects this even on Windows)
             bash_wrapper_path.chmod(0o755)
 
-            info('Created both .cmd (for PowerShell/CMD) and bash wrapper (for Git Bash)')
+            info('Created wrappers for all Windows shells (PowerShell, CMD, Git Bash)')
 
             # Add .local/bin to PATH if not already there
             user_path = os.environ.get('PATH', '')
@@ -507,6 +538,7 @@ def register_global_command(launcher_path: Path) -> bool:
 
         if system == 'Windows':
             success('Created global command: claude-python (works in PowerShell, CMD, and Git Bash)')
+            info('The command now works in all Windows shells!')
         else:
             success('Created global command: claude-python')
         return True

system-prompts/README.md

@@ -47,26 +47,36 @@ As of Claude Code v1.0.51, the `--append-system-prompt` flag works in interactiv
 
 ```bash
 # Start Claude Code with a specific role
+# Git Bash/Linux/macOS:
 claude --append-system-prompt "$(cat system-prompts/examples/python-developer.md)"
 
-# Or reference the file directly
+# Or reference the file directly (may not work on all systems)
 claude --append-system-prompt @system-prompts/examples/python-developer.md
+
+# Windows (PowerShell/CMD) - use the automated setup script which creates working wrappers
 ```
 
+**Windows Users**: The `$(cat file)` syntax works in Git Bash. For PowerShell and CMD, use the automated setup which creates proper wrappers.
+
 ### Using System Prompts in Non-Interactive Mode
 
 ```bash
 # Execute a task with a specific system prompt
+# Git Bash/Linux/macOS:
 claude -p "Review this codebase for security issues" \
-  --append-system-prompt @system-prompts/examples/python-developer.md
+  --append-system-prompt "$(cat system-prompts/examples/python-developer.md)"
+
+# Windows users: Use the claude-python command after running setup
 
 # Combine with other flags
 claude -p "Optimize database queries" \
-  --append-system-prompt @system-prompts/examples/python-developer.md \
+  --append-system-prompt "$(cat system-prompts/examples/python-developer.md)" \
   --model opus \
   --max-turns 10
 ```
 
+**Note**: The `@file` syntax may not work reliably. Use `$(cat file)` for better compatibility.
+
 ## 📚 Available System Prompts
 
 ### Python Developer (`python-developer.md`)

technical-docs/APPEND_SYSTEM_PROMPT_CMD.md

@@ -0,0 +1,66 @@
+Here is a precise, end-to-end explanation of why the **CMD** one-liner works and what each part does:
+
+```cmd
+"C:\Program Files\Git\bin\bash.exe" -lc "p=$(tr -d '\r' < ~/.claude/prompts/python-developer.md); exec claude --append-system-prompt=\"$p\""
+```
+
+# 1) What CMD contributes
+
+* **`"C:\Program Files\Git\bin\bash.exe"`**
+  In `cmd.exe`, double quotes group a path with spaces into a single token, so the program launched is Git Bash. Inside a quoted argument for a Windows program, backslash-quote `\"` is the standard way to embed a literal double quote in the same argument, per the Microsoft C runtime command-line parsing rules that most Windows programs use. ([Microsoft Learn][1])
+
+* **Everything after that becomes arguments to `bash.exe`**
+  `-l` asks Bash to run as a login shell, and `-c "…"` tells Bash to execute the given command string. CMD passes that entire string as one argument because it is wrapped in double quotes. Also note that characters like `&` and `|` are special in CMD, which is why wrapping the `-c` payload in quotes is required to avoid CMD’s own metacharacter parsing. ([Microsoft Learn][2])
+
+* **Command-line length caveat**
+  CMD itself imposes about **8191** characters as the maximum command-line length. Your line stays far under that, so it executes reliably, but it is a useful limit to remember when you embed long data. The underlying Win32 `CreateProcess` API allows up to **32767** characters, however when you invoke via CMD you are bound by CMD’s lower limit. ([Microsoft Learn][3], [Microsoft for Developers][4])
+
+# 2) What Bash does with `-lc "…"`
+
+The string given to `-c` is parsed by Bash, not by CMD. Inside that string:
+
+* **`~/.claude/prompts/python-developer.md`**
+  Tilde expansion happens in Bash, `~` becomes the current user’s home. In Git Bash, home maps to your Windows profile directory and POSIX-style drive prefixing is used, for example `/c/Users/<name>`. ([GNU][5], [MSYS2][6])
+
+* **`< file` input redirection**
+  The `<` operator redirects the named file to the standard input of the command on its left. Here it feeds the prompt file into `tr`. ([GNU][7])
+
+* **`tr -d '\r'`**
+  `tr` is run from GNU coreutils. With `-d`, `tr` deletes every occurrence of the characters listed, so `'\r'` strips Windows carriage returns, leaving clean LF line endings. That prevents odd parsing issues when multi-line text later becomes a single shell argument. ([GNU][8])
+
+* **`p=$( … )` command substitution**
+  `$( … )` runs the command and substitutes its standard output. Bash captures all bytes from `tr` and assigns them to the variable `p`. Trailing newlines are removed, embedded newlines are preserved, which is exactly what you want for a multi-line system prompt. ([GNU][9])
+
+* **`exec claude --append-system-prompt="$p"`**
+  `exec` replaces the current Bash process with the `claude` CLI, so you do not keep an extra shell in the foreground. The value expansion is **double-quoted**, which is the critical part. In Bash, double quotes suppress word splitting and globbing, so the entire multi-line value in `p` is passed to `--append-system-prompt` as one argument, even if the first line begins with `---`. This avoids the classic “unknown option '---'” failure that happens when a multi-line value is accidentally split into separate argv tokens. ([GNU][10])
+
+# 3) Why this pattern succeeds where others fail
+
+* **CMD’s quoting and metacharacters are tricky**
+  Without the outer double quotes, CMD would try to interpret `&`, `|`, `(`, and `)` in your Bash payload, which would corrupt the command. Quoting once at the CMD layer hands one opaque argument to `bash.exe`, and all further parsing is done by Bash, which is what you want here. ([Microsoft Learn][2])
+
+* **The value is bound to the flag as a single argv element**
+  The combination of Bash variable assignment, quoting, and `exec` ensures `claude` receives exactly two things for this feature, the flag name and one value string. Because the value is already the next argv item, the CLI parser treats it as data, not as another option, even if its first characters are `---`. The “single argument” property comes from Bash’s word-splitting rules, which say that expansions enclosed in double quotes are not split. ([GNU][11])
+
+* **CRLF normalization prevents stray `\r` from leaking**
+  CR characters in Windows-created files can sneak into an argument and confuse downstream parsers. Removing `\r` with `tr -d '\r'` is a simple, POSIX-friendly way to normalize the text before it becomes an argument. ([GNU][8])
+
+# 4) Micro-timeline of execution
+
+1. `cmd.exe` launches `bash.exe` with `-lc "<payload>"`. The quotes make the payload one argument, and embedded `\"` sequences survive as literal quotes inside that argument per the CRT argument rules. ([Microsoft Learn][1])
+2. Bash, as a login shell due to `-l`, executes the `-c` string. It expands `~`, redirects the file into `tr`, deletes `\r`, and captures the result in `p` via command substitution. ([GNU][5])
+3. Bash runs `exec claude --append-system-prompt="$p"`. Because `$p` is double-quoted, it is passed as one multi-line value. The shell process is replaced by the CLI, so the terminal is attached directly to `claude`. ([GNU][10])
+
+That is the complete mechanics behind your working CMD line.
+
+[1]: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments?view=msvc-170&utm_source=chatgpt.com "Parsing C command-line arguments"
+[2]: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd?utm_source=chatgpt.com "cmd"
+[3]: https://learn.microsoft.com/en-us/troubleshoot/windows-client/shell-experience/command-line-string-limitation?utm_source=chatgpt.com "Command prompt line string limitation - Windows Client"
+[4]: https://devblogs.microsoft.com/oldnewthing/20031210-00/?p=41553&utm_source=chatgpt.com "What is the command line length limit? - The Old New Thing"
+[5]: https://www.gnu.org/s/bash/manual/html_node/Tilde-Expansion.html?utm_source=chatgpt.com "Tilde Expansion (Bash Reference Manual)"
+[6]: https://www.msys2.org/docs/filesystem-paths/?utm_source=chatgpt.com "Filesystem Paths"
+[7]: https://www.gnu.org/s/bash/manual/html_node/Redirections.html?utm_source=chatgpt.com "Redirections (Bash Reference Manual)"
+[8]: https://www.gnu.org/software/coreutils/manual/html_node/index.html?utm_source=chatgpt.com "Top (GNU Coreutils 9.7)"
+[9]: https://www.gnu.org/s/bash/manual/html_node/Command-Substitution.html?utm_source=chatgpt.com "Command Substitution (Bash Reference Manual)"
+[10]: https://www.gnu.org/software/bash/manual/html_node/Shell-Builtin-Commands.html?utm_source=chatgpt.com "Shell Builtin Commands (Bash Reference Manual)"
+[11]: https://www.gnu.org/software/bash/manual/html_node/Word-Splitting.html?utm_source=chatgpt.com "Word Splitting (Bash Reference Manual)"