---
slug: "pi-windows-path-guard"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Lododizzle/pi-windows-path-guard@main/README.md"
repo: "https://github.com/Lododizzle/pi-windows-path-guard"
source_file: "README.md"
branch: "main"
---
# pi-windows-path-guard

A tiny Pi extension for Windows users.

## Problem

Pi may use Git Bash for shell commands. Git Bash reports paths as `/c/Users/...`. If an agent passes that path into Windows-native file tools (read, write, edit), Node.js can resolve it to `C:\c\Users\...` instead of `C:\Users\...`.

This creates a **false-success trap**: the agent reports "Successfully wrote X bytes", but the file lands in a phantom tree that Windows applications cannot find.

## Behavior

This extension guards Pi file tool calls before execution:

| Path format | Action |
|-------------|--------|
| `/c/Users/...` | Normalizes to `C:\Users\...` |
| `/mnt/c/Users/...` | **Blocks** in Windows-native mode |
| `C:\c\Users\...` | **Blocks** as a known mangled trap |
| `C:\mnt\c\Users\...` | **Blocks** as a known mangled trap |
| `C:\Users\...` | Allows native Windows paths |
| `\\wsl.localhost\...` | Allows intentional UNC access |
| `\\wsl.localhost\Ubuntu-24.04\...` | Allows WSL UNC paths |

## Install

```bash
pi install npm:pi-windows-path-guard
```

Or load directly for testing:

```bash
pi -e ./src/index.ts
```

## Why

This prevents false-success writes where:
- Agent sees bash pwd as `/c/Users/DESKTOP/workspaces`
- Agent uses that path for write/read/edit
- File lands at `C:\c\Users\DESKTOP\workspaces\...`
- VLC, PowerShell, and Windows apps cannot find the file

## Proof

**Before (without extension):**

```
write /c/Users/Me/workspace/file.txt "content"
→ write tool: "Successfully wrote 7 bytes"
→ actual location: C:\c\Users\Me\workspace\file.txt
→ PowerShell Test-Path C:\Users\Me\workspace\file.txt: False
```

**After (with extension):**

```
write /c/Users/Me/workspace/file.txt "content"
→ extension normalizes to C:\Users\Me\workspace\file.txt
→ write tool: "Successfully wrote 7 bytes"
→ actual location: C:\Users\Me\workspace\file.txt
→ PowerShell Test-Path C:\Users\Me\workspace\file.txt: True
```

**Blocked paths:**

```
write /mnt/c/Users/Me/workspace/wsl.txt
→ Blocked: "Blocked Windows path dialect trap: /mnt/c/... Use native Windows path C:\Users\..."

write C:\c\Users\Me\workspace\bad.txt
→ Blocked: "Blocked Windows path dialect trap: C:\c\... Use native Windows path C:\Users\..."
```

## Guarded Tools

- `read`
- `write`
- `edit`
- `grep`
- `find`
- `ls`

## Security Note

This extension intercepts all file tool calls on Windows and may block or mutate paths. Review the source before installing third-party Pi packages.

Source: [GitHub](https://github.com/sensei/pi-windows-path-guard)

## License

MIT