Fix AI coding agents on Windows: 4 shell problems solved
You paste the chat’s suggestion into the terminal, run the tests, copy the error back. You’re a slow USB cable between the model and your machine. Agent modes were supposed to end that loop. On Windows, they often don’t.
Peter Mamrukov, who maintains the open source MCP server local-commander-mcp-agent (MIT licensed), documented the root causes and the fixes. Here’s the condensed version for Windows developers running AI coding agents today.
Two Failures You Keep Hitting
The first failure: the agent writes a command your shell won’t parse. It chains steps with && in Windows PowerShell 5.1, mangles backslashes, or runs a bash-style command that resolves to a different Windows binary. A Cursor forum thread describes PowerShell in Cursor as “consistently broken.” A Claude Code issue reports that native Windows runs aren’t shell-aware: move not found, backslashes broken, find resolving to the Windows binary instead of the Unix one.
The second failure: the agent starts a dev server and the chat never comes back. npm run dev doesn’t exit, so the tool call waits forever. One Cursor user put it plainly: “I have to manually kill it.” Kill the terminal and the server often holds its port anyway.
Both failures trace to the same cause. The agent is handed a terminal and expected to type into it like a person. A person knows which shell they’re in and when to stop waiting. A model guesses.
️ Fix 1: Pass a Program and Arguments, Not a Command String
Most quoting bugs disappear when nothing parses a command line. Start real executables directly instead of handing a shell a string to interpret.
In Node.js, use execFile instead of exec:
// Node: no shell in between
import { execFile } from "node:child_process";
execFile("git", ["status", "--short"], { cwd: "C:\work\my-app" }, (err, stdout, stderr) => { /* ... */ });In Python, pass a list and skip shell=True:
# Python: a list, and no shell=True
subprocess.run(["git", "status", "--short"], cwd=r"C:workmy-app", check=True)One Windows catch to know about: npm, npx, pnpm, and yarn are usually .cmd shims. Since Node’s April 2024 security release, spawning a .cmd or .bat file requires shell: true, which brings cmd.exe back into the picture. Keep that safe by refusing arguments that contain cmd metacharacters (& | < > ^ % !) and quoting each argument yourself, or by running node directly on the tool’s JavaScript entry point.
If your agent talks to tools over MCP, prefer a command tool that accepts command and args as separate fields rather than one that takes a raw shell string.
Fix 2: Block PowerShell Mistakes Before They Run
A rule in your agent’s instructions is a hint. A hook is enforced.
In Claude Code, a PreToolUse hook with the PowerShell matcher intercepts every command before execution. Exit code 2 blocks it and sends your message back to the model:
import json, sys
cmd = json.load(sys.stdin).get("tool_input", {}).get("command", "")
if "<<" in cmd:
sys.stderr.write("PowerShell has no heredoc. Write the file with the Write tool, or use a @'...'@ here-string.")
sys.exit(2)The model reads the error message and retries a different way. The same pattern catches && on Windows PowerShell 5.1, or helper functions named after built-in aliases like rd.
⏱️ Fix 3: Treat Dev Servers as Processes, Not Terminal Sessions
Start long-running servers in the background and check on them separately. When one gets left behind, the port tells you where it is:
netstat -ano | findstr :5173
taskkill /PID <pid> /T /FThe PID is the last column of the LISTENING line. The /T flag stops the process together with everything it started. For Vite, that includes esbuild. Plain Stop-Process only takes the one PID and leaves child processes running.
Before trusting a log line that says “ready,” actually ask the server if it’s there:
curl.exe -s -o NUL -w "%{http_code}" http://localhost:5173/curl.exe ships with current Windows 10 and 11. A 200 response is worth more than any log message.
Fix 4: Know Where Your Guard Rails End
Restricting an agent to certain folders and keeping it away from .env files and private keys stops everyday accidents. People have watched agents read secret files and delete home directories. Those are mostly habit failures, and habits can be blocked at the tool level.
But none of that is a real sandbox. If node or python is allowed, a script can do anything your account can do, including deleting files. For an actual hard boundary, run the agent’s tools in a container, under a separate low-privilege account, or in a VM.
Where These Fixes Come From
Mamrukov built local-commander-mcp-agent, an open source MIT-licensed MCP server that packages fixes 1, 3, and part of 4 for agents working on Windows. It was built specifically around these problems.
If you have a Windows setup that still trips your agent up, whether that’s unusual paths, non-English usernames, or locked-down corporate machines, the fix is almost always one of these four categories. Start with how your agent spawns processes and work outward from there.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
