fauxnix

Run Linux-style commands on Windows — natively, deterministically, no VM, no WSL.

fauxnix is a bash→PowerShell translation layer built for AI agents. Your agent keeps writing the bash it already knows (ls -la | grep foo, find . -name '*.ts' | wc -l, kill -9 1234), and 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, UTF-8/GBK handled automatically.

One-command install for Claude Code · Codex · OpenCode · Kimi Code · Qwen Code, plus any MCP client. 109 translated commands · 1,044 automated tests · 270-case Git Bash differential corpus plus 41 supplementary checks · zero LLM calls at runtime.

This checkout prepares v2.0.0. See migration and release notes for the Node.js requirement, changed file-operation contracts and verification limits. The npm badge and @latest examples show the published version until publication completes.

Try it now — no install

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

$ fauxnix "ls -la src | head -2"
-rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
-rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts

$ fauxnix "cat nope.txt"
cat: nope.txt: No such file or directory        # not a PowerShell stack trace

Connect your agent — one command

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

Idempotent; prints exactly what changed. Manual configurations below if you prefer to edit config files yourself.

npm package name is fauxnix-cli (the fauxnix name on npm belongs to an unrelated 2015 websocket library); the installed command is fauxnix. Requires Windows with PowerShell 5.1+ (built-in) and Node.js ≥ 22.20.0. Node 18/20 are unsupported in v2. Current Node 22/24 LTS patches are tested. Published v1.0.0 retains its original metadata.

Manual config per harness

Claude Code

claude mcp add fauxnix -- fauxnix mcp

Codex (~/.codex/config.toml or codex mcp add fauxnix -- fauxnix mcp)

[mcp_servers.fauxnix]
command = "fauxnix"
args = ["mcp"]

Note: in non-interactive codex exec mode, MCP tool calls are auto-denied by the approval layer; pass --dangerously-bypass-approvals-and-sandbox (or run interactively and approve once).

OpenCode (opencode.json)

{
  "mcp": {
    "fauxnix": { "type": "local", "command": ["fauxnix", "mcp"] }
  }
}

Kimi Code — MCP servers live in a JSON file, not the TOML config: ~/.kimi-code/mcp.json

{
  "mcpServers": {
    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
  }
}

Qwen Code (~/.qwen/settings.json)

fauxnix install --qwen

The installer preserves the rest of settings.json and writes an absolute Node + package-entry launcher so Qwen startup does not depend on its working directory or PATH order. See the Qwen example for the generated JSON shape.

Any MCP client — stdio server: fauxnix mcp. The tool name is bash (override with FAUXNIX_TOOL_NAME). The tool description already teaches the model the supported subset, so no system-prompt changes are required.

Copy-paste quickstarts with a 10-command smoke test per harness: docs/examples/

The MCP session persists cwd, environment variables, export/unset, cd -/OLDPWD, and positional parameters (set -- / $1 / "$@") across tool calls — it behaves like a logged-in shell, not a stateless exec. $0 is the MCP tool name, not a Windows path.

For workflows whose commands are already known, the MCP server also exposes bash_batch: it compiles every step before execution, runs the plan atomically in one session, and returns one structured result per step in a single MCP round trip (stops on first nonzero exit by default).

{
  "steps": [
    { "id": "write", "command": "printf 'a\\r\\nb' > data.txt" },
    { "id": "measure", "command": "wc -c data.txt" }
  ]
}

See compiled MCP batch plans for timeout, budget, cancellation, and preflight semantics.

Experimental: native shell facade

Point Claude Code's built-in Bash tool at fauxnix — no MCP sidecar, zero protocol round trips per command:

fauxnix install --claude-shell     # builds a fauxnix-backed bash.exe (~85 MB) and sets
                                   # CLAUDE_CODE_GIT_BASH_PATH; restart Claude Code after
fauxnix doctor                     # reports the launcher status
fauxnix install --claude-shell-off # restores the previous setting

The launcher is a copy of your own node.exe with the facade bundle injected via Node SEA (experimental trade-off; the GA plan is a small prebuilt stub). It implements the bash argv contract (bash -c/-lc, $0/$1 from trailing operands), adapts the harness's private command scaffolding (captured from a live session — payload execution, cwd markers, snapshot stubs), and always identifies itself via --version. The harness's own Bash approval flow governs runs. fauxnix facade also runs standalone. Details, security rules, and the protocol findings: RFC — native shell facade.

Measured: your model is probably worse at PowerShell than you think

Same model (DeepSeek-V4-Pro), same 5 tasks, three execution modes on one Windows machine — full data in docs/benchmark-deepseek-v4-pro.md and docs/benchmark-ark-models.md:

	PowerShell	fauxnix	Git Bash
tool calls / unexpected errors	14 / 9	7 / 0	4 / 0
time (T1–T4)	163s	66s	57s

Across 7 models on the Volcan