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.

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:

Across 7 models on the Volcano Ark Coding Plan, the PowerShell-vs-fauxnix gap held for every model tested — worst case (kimi-k2-thinking): 3.1× slower with 24 error events writing PowerShell vs zero errors through fauxnix. fauxnix lands within ~15% of the real-bash ceiling with no bash toolchain installed.

Why

LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so models on Windows often produce "looks right, doesn't run" commands (wrong quoting, curl that isn't curl, mojibake from codepage mismatches, inscrutable CategoryInfo error dumps).

If Git Bash already works for you, keep it — we literally use it as our differential-testing oracle. fauxnix is for when you can't or don't want to ship one: agent fleets where the bash toolchain drifts or isn't detected (the Windows ARM64 Git-Bash detection failure is a live example), CI runners, locked-down machines, or anywhere a single npm install -g is easier than a toolchain.

fauxnix takes the third road: translate, don't emulate. A large, high-value subset of the Linux command line — file ops, text processing, process management, archives, networking basics — maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and fails loudly and helpfully on what it can't translate, so the agent never gets silently-wrong results. That matters as labs train computer-use agents on Mac fleets — the agent keeps writing bash; fauxnix makes the Windows box answer like the box the agent was trained on (RFC: computer-use parity).

What's translated

109 commands, output-matched against real GNU coreutils on Windows (Git Bash) during development:

• files: ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff
• text filters: grep egrep sed awk sort uniq cut tr — sed/awk scripts are parsed while preparing an executable plan (unsupported constructs throw named errors, never silently misbehave)
• text I/O: echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs
• shell/system: cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami id groups date uname hostname uptime free nproc clear true false test [ [[ : pushd popd dirs sudo timeout man history less more source . eval exit alias set shift
• network: curl wget ping netstat ss ip ifconfig nslookup dig host
• archives: tar gzip gunzip zcat zip unzip

The curated agent-daily 60 carry a CommandSpec: unknown options fail with a GNU-style usage error instead of being ignored. The generated docs/command-specs.md is the exact list, coverage count, option table, and exclusion rationale; fauxnix list --json exposes the same per-command