20000419/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
Connect your agent — one command
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**
**Codex** (~/.codex/config.toml or codex mcp add fauxnix -- fauxnix 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)
**Kimi Code** — MCP servers live in a JSON file, not the TOML config: ~/.kimi-code/mcp.json
**Qwen Code** (~/.qwen/settings.json)
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).
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:
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