fauxnix MCP
fauxnix translates an agent's bash commands into PowerShell and runs them on Windows with no WSL or VM, returning GNU-style output and error messages
- 903 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Runs translated commands directly in PowerShell on your system, including deleting and moving files
- The experimental mode replaces Claude Code's built-in Bash tool with a built binary based on node.exe
- The MCP session holds environment variables and the working directory across calls, including values the agent set itself
Install
- Works in
Manual install
npm install -g fauxnix-cliAfter installing, run fauxnix install --claude (or --codex, --opencode, --kimi, --qwen) and fauxnix doctor to verify.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs translated commands directly in PowerShell on your system, including deleting and moving files
- The experimental mode replaces Claude Code's built-in Bash tool with a built binary based on node.exe
- The MCP session holds environment variables and the working directory across calls, including values the agent set itself
This is third-party code. Review the repository files before installing.
What it does
fauxnix is a command-translation layer for an agent on Windows: the agent writes the plain bash it already knows (`ls -la | grep foo`, `find . -name '*.ts' | wc -l`), and fauxnix deterministically translates each command into PowerShell, runs it through .NET and returns output in GNU format: `ls -l` columns, bash-style error messages instead of `CategoryInfo` dumps, coreutils exit codes, automatic UTF-8 and GBK handling. 109 commands are translated — file operations, text processing, process management, archives, basic networking — checked line by line against real GNU coreutils through Git Bash during development. The `fauxnix mcp` command starts a stdio MCP server with one `bash` tool (renamed via `FAUXNIX_TOOL_NAME`) that keeps a session like a logged-in shell: it persists the working directory, environment variables, exports and `cd -` across tool calls instead of running each command from scratch. The `bash_batch` tool compiles a whole multi-step plan before execution, runs it atomically in one session and stops at the first step with a nonzero exit code unless told otherwise. Running `fauxnix install --claude` wires the MCP server into Claude Code in one command, and the experimental `fauxnix install --claude-shell` mode replaces Claude Code's built-in Bash tool with a built binary based on node.exe that answers bash syntax itself, with no separate MCP server and no extra protocol round trip per command.
Who it is for. For anyone running agents on Windows without WSL or Git Bash who wants the agent to keep writing the bash it knows and get GNU-formatted results instead of raw PowerShell output.
Good fit when
- An agent on Windows writes bash commands and PowerShell returns them in an unfamiliar format or with parsing errors
- There's no way to install WSL or Git Bash on the machine the agent runs on: that needs a VM or several gigabytes
- Agents run across a fleet of different Windows machines where the installed bash toolchain is unpredictable
- You need a shell session that remembers the working directory and variables between tool calls instead of running each command from scratch
Not a fit when
- A working Git Bash is already on the machine: the authors say to keep it, since fauxnix itself uses Git Bash as the reference oracle when testing its translation
- You need a command outside the 109 translated ones: the tool only covers a defined bash subset, not the whole shell
- Node.js is older than 22.20.0: earlier Node 18 and 20 builds are unsupported in this version
- You're not on Windows: the tool translates bash into PowerShell specifically for Windows, and has no purpose on another system
Example request
Find every .log file in the project older than 7 days and show their size, use plain bash commandsMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
FAUXNIX_TOOL_NAME- Renames the bash tool if the name is taken in the client
Limitations
License is MIT.
- Needs Windows with PowerShell 5.1 or later (built in) and Node.js 22.20.0 or later; earlier Node 18 and 20 builds are unsupported in this version.
- The translated subset covers 109 commands across file operations, text processing, process management, archives and basic networking, not the whole Linux shell: on an untranslated command the tool stops with a clear error instead of running it approximately.
- The experimental `--claude-shell` mode replaces Claude Code's built-in Bash with an approximately 85 MB copy of node.exe with logic injected via Node SEA; the author calls it a stopgap trade-off ahead of a smaller prebuilt stub.
- The npm package name is `fauxnix-cli`, not `fauxnix`: the short name is already taken by an unrelated 2015 websocket library, while the installed command is still called `fauxnix`.
- In non-interactive `codex exec` mode, MCP tool calls are denied by Codex's approval layer by default; this needs either a sandbox-bypass flag or an interactive run with manual confirmation.
How to disable. Run `fauxnix install --claude-shell-off` to restore Claude Code's previous Bash setting, then remove the fauxnix entry from the MCP configuration (`claude mcp remove fauxnix`) or drop the `mcpServers`/`mcp` block for fauxnix from another client's config, and finally `npm uninstall -g fauxnix-cli`.
FAQ
Does fauxnix need WSL to work?
No, that's the main difference from WSL: fauxnix doesn't spin up a VM and doesn't weigh gigabytes; it translates commands directly into PowerShell through .NET. The only dependency besides Windows is Node.js 22.20.0 or later.
What happens if the agent writes a command fauxnix can't translate?
The tool stops with a clear error instead of running the command approximately and returning a wrong result. The author calls this the 'fail loudly' rule: an explicit refusal beats a silently wrong answer.
How is bash_batch different from calling bash one command at a time?
bash_batch first compiles a whole multi-step plan, then executes it atomically in one session and returns one structured result per step in a single MCP round trip. By default, execution stops at the first step with a nonzero exit code.
What is the experimental --claude-shell mode?
It replaces Claude Code's own built-in Bash tool with a built copy of node.exe with fauxnix's logic injected, so commands run with no separate MCP server and no protocol round trip per call. The author calls the roughly 85 MB build a stopgap ahead of a smaller prebuilt binary.
Does the working directory persist between the agent's commands?
Yes, fauxnix's MCP session behaves like a logged-in shell: the working directory, environment variables, export, unset and cd - persist across bash tool calls instead of resetting on every command.
Discussion
No questions or reviews yet.
Related
MCP serversSSH MCP Server (classfang): remote commands over SSH
SSH MCP Server (classfang)
An SSH MCP server: the agent runs commands, reads and writes files over SFTP, transfers files and starts long jobs while credentials stay with you
MCP SSH Manager
mcp-ssh-manager
Managing several SSH connections from Claude Code and Codex: commands, file transfer, databases and backups
An MCP server for NixOS resources: search packages and options so the agent does not invent names and settings
The MCP server of the purple SSH manager: an agent reads hosts from ~/.ssh/config and their containers, commands and container control are opt-in
SSH MCP
ssh-mcp
A security-first SSH server: command classification, policy authorization and several sign-in methods. It runs commands on remote servers
A native macOS terminal built on Ghostty with vertical tabs and notifications when an agent needs your input
README in short
The repository description opens with npm version, download-count and Glama-directory score badges, and the first block gives an npx command for a no-install trial run. A separate 'Measured' section carries a comparison table against plain PowerShell on one model and five tasks, plus links to full measurements across seven models. A table of translated commands by category (files, text, processes, archives, networking) and a list of known translation limits close out the description.