fauxnix: deterministic bash-to-PowerShell translation so agents keep writing Linux commands on Windows

Letting an agent write bash on a Windows machine

fauxnix is a bash-to-PowerShell translation layer built for AI agents. The problem it targets is specific: an agent trained on Linux keeps writing bash like `ls -la | grep foo`, `find . -name '*.ts' | wc -l` or `kill -9 1234`, but it is running on Windows where those commands do not exist. fauxnix deterministically translates each command into PowerShell, executes it natively, and hands back output that looks like GNU/Linux, `ls -l` columns, bash-style error messages, coreutils exit codes, with UTF-8 and GBK handled automatically.

The user is someone running an AI coding agent on Windows who wants it to behave as if it were on Linux without the overhead of a VM or WSL. The README lists one-command install for Claude Code, Codex, OpenCode, Kimi Code and Qwen Code, plus any MCP client, so it is aimed squarely at the agent-harness use case.

The distinguishing word is deterministic. fauxnix does not ask a model to guess the PowerShell equivalent; it translates each command through a fixed mapping, which the README backs with 109 translated commands, 400-plus automated tests and a 253-case differential corpus verified against real behavior. That determinism is what makes it trustworthy in an automated loop where a wrong translation would silently corrupt a step.

Why deterministic translation beats a guess or a VM

The design choice at the center is that translation is a fixed, tested mapping rather than an LLM inference or a full emulation. That matters for agents specifically. If an agent's shell commands were translated by another model call, you would add latency, cost and a second source of error into every command; if they ran in a VM or WSL, you would add heavy setup and a separate environment to manage. fauxnix runs the translated command natively in PowerShell on the same machine, so there is no VM, no WSL and no second runtime.

The output fidelity is the other half. The README stresses that results look like GNU/Linux, not PowerShell: `ls -l` produces Unix-style columns, a missing file yields `cat: nope.txt: No such file or directory` rather than a PowerShell stack trace, and exit codes match coreutils. That fidelity matters because an agent parses command output, and output that looks like Linux is output the agent already knows how to read.

The verification numbers, 400-plus automated tests and a 253-case differential corpus, are the credibility behind the determinism claim. A translation layer is only useful if it is correct, and the differential corpus, checking fauxnix output against reference behavior case by case, is exactly the kind of testing that justifies trusting it in an automated pipeline.

Installing and wiring it into an agent

fauxnix can be run ad hoc with npx or installed globally. The quickest trial translates and runs a command directly:

npx fauxnix-cli@latest "ls -la src | head -3"
npx fauxnix-cli@latest translate "find . -name '*.log' -mtime +7 -delete"

For an agent setup, the README installs it globally and wires it into a harness in one step, then verifies:

npm install -g fauxnix-cli
fauxnix install --claude     # or --codex / --opencode / --kimi / --qwen
fauxnix doctor               # verifies encoding, harness config, and MCP round-trip

`fauxnix install --claude` configures the named agent, and `fauxnix doctor` checks encoding, the harness configuration and the MCP round-trip so you know it is actually working. As an MCP server it can be registered directly, for example with Claude Code:

claude mcp add fauxnix -- fauxnix mcp

The README also shows the raw MCP server config for a TOML-based client, mapping a `fauxnix` server to the command `fauxnix` with args `["mcp"]`. Because it distributes as the npm package `fauxnix-cli` and speaks MCP, it fits both a direct-CLI workflow and any MCP client beyond the named agents.

The limitation: a translation layer, not a Linux environment

The honest limitation is that fauxnix translates commands; it does not provide Linux. The README's own figure is 109 translated commands, which is a broad and practical set for coding-agent workflows, but it is a defined set, not the entirety of GNU/Linux userland. A command outside that set, or an obscure flag combination, is where translation stops, and an agent relying on the full breadth of a real shell will eventually hit an edge the mapping does not cover.

The deterministic approach that makes fauxnix trustworthy is also what bounds it: because it maps known commands rather than emulating a system, its coverage is exactly its tested command-and-flag set, and it does not run actual Linux binaries. Something that genuinely needs a Linux binary, not a coreutils-equivalent behavior, is outside fauxnix's scope by design and would still need WSL or a VM.

That is the right trade for the target use case, agents doing ordinary file and text operations on Windows, but it means fauxnix is a compatibility layer for common commands, not a drop-in replacement for a Linux environment. Knowing where its 109-command coverage ends is the thing to establish before depending on it for a complex workflow.

Against WSL or a real VM

The alternatives are WSL, which runs a genuine Linux environment on Windows, or a full virtual machine. Both give you real Linux, the complete userland and actual binaries, which fauxnix does not. That is their advantage: unlimited command coverage and true compatibility.

The cost is exactly what fauxnix removes. WSL and a VM are separate environments with their own setup, filesystems and integration friction, and for an agent they mean commands run somewhere other than the native Windows machine, which complicates file paths and process management. fauxnix runs translated commands natively in PowerShell on the same machine with no second environment, deterministically and with Linux-looking output, which is lighter and integrates directly into an agent harness. Choose WSL or a VM when you need a real, complete Linux environment and actual binaries. Choose fauxnix when you want an agent to keep writing familiar bash for common file and text operations on native Windows, without standing up or managing a separate Linux system, and its 109-command coverage spans what your agent actually uses.

MIT, npm and MCP, and where to start

fauxnix is MIT and distributed as the npm package `fauxnix-cli`, so it can be forked, inspected and adapted with attribution, and its dual nature as a CLI and an MCP server means it fits both direct use and any MCP client. That breadth, plus one-command installers for five named agents, is what makes it low-friction to adopt into an existing setup.

Upgrade cost is the ordinary npm one, and because translation is a fixed, tested mapping, updates that expand the command set or fix a translation are exactly the kind of change the 400-plus tests and differential corpus are meant to guard, so growth in coverage comes with verification rather than regression risk.

The concrete first step is to verify it works in your setup before trusting it in a loop: run `fauxnix doctor` after installing, which checks encoding, harness config and the MCP round-trip, and try a few of your agent's typical commands through `npx fauxnix-cli@latest` to confirm the translations and the GNU/Linux-style output match what the agent expects. Establish which of your common commands fall inside the 109-command coverage, since that boundary is what determines whether fauxnix can replace a heavier WSL or VM setup for your workflow.

Editorial conclusion

Use fauxnix if you run an AI coding agent on Windows and want it to keep writing the bash it knows, translated deterministically into native PowerShell with GNU/Linux-style output, without standing up WSL or a VM: the fixed, tested mapping (109 commands, a 253-case differential corpus) and the one-command installers for Claude Code, Codex and others are its strengths. It is the wrong choice when you need a real, complete Linux environment or actual Linux binaries, which only WSL or a VM provide, since fauxnix translates a defined command set rather than emulating a system. Start by installing fauxnix-cli, running fauxnix doctor to verify encoding and the MCP round-trip, and testing your agent's typical commands through npx to confirm coverage before relying on it.

Frequently asked questions

Official sources

1. 20000419/fauxnix on GitHub
2. Issues
3. License: MIT
4. README
5. Releases