fauxnix
Run Linux-style commands on Windows via deterministic bash→PowerShell translation. No VM, no WSL. MCP server + CLI built for AI agents (Claude Code, Codex, OpenCode...). GNU-style output, bash-style errors, UTF-8/GBK handled.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/20000419--fauxnix)HTML
<a href="/listings/20000419--fauxnix"><img src="/api/listings/20000419--fauxnix/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 358 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # fauxnix
- [](https://github.com/20000419/fauxnix/actions/workflows/ci.yml)
- [](https://www.npmjs.com/package/fauxnix-cli)
- [](https://www.npmjs.com/package/fauxnix-cli)
- [](LICENSE)
- [](https://glama.ai/mcp/servers/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,469 automated tests · 270-case Git Bash differential
- corpus plus 41 supplementary checks · zero LLM calls at runtime.**
- This checkout is **v2.2.0**. See [migration and release notes](docs/releases/v2.0.0.md)
- 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
- ```bash
- 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
- ```bash
- 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.
- <details>
- <summary><b>Manual config per harness</b></summary>
- `fauxnix install --<harness>` writes the **spawn-safe** form shown below: the absolute Node
- executable plus this installation's absolute entry. A bare `command: "fauxnix"` is an
- extension-less npm shim on Windows — MCP clients that spawn the server directly (CreateProcess)
- cannot execute it (#252). Shell-wrapping clients like Claude Code accept either form; the
- absolute form works everywhere.
- **Claude Code**
- ```bash
- claude mcp add fauxnix -- fauxnix mcp
- ```
- **Codex** (`~/.codex/config.toml` or `codex mcp add fauxnix -- fauxnix mcp`)
- ```toml
- [mcp_servers.fauxnix]
- command = 'C:\Program Files\nodejs\node.exe'
- args = ['C:\Users\<you>\AppData\Roaming\npm\node_modules\fauxnix-cli\dist\index.js', '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`)
- ```json
- {
- "mcp": {
- "fauxnix": {
- "type": "local",
- "command": ["C:\\Program Files\\nodejs\\node.exe", "C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\fauxnix-cli\\dist\\index.js", "mcp"]
- }
- }
- }
- ```
- **Kimi Code** — MCP servers live in a JSON file, not the TOML config: `~/.kimi-code/mcp.json`
- ```json
- {
- "mcpServers": {
- "fauxnix": {
- "command": "C:\\Program Files\\nodejs\\node.exe",
- "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\fauxnix-cli\\dist\\index.js", "mcp"]
- }
- }
- }
- ```
- **Qwen Code** (`~/.qwen/settings.json`)
- ```bash
- fauxnix install --qwen
- ```
- The installer preserves the rest of `settings.json` and writes the same absolute launcher.
- See [the Qwen example](docs/examples/qwen.md) 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/`](docs/examples/)
- </details>
- 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).
- ```json
- {
- "steps": [
- { "id": "write", "command": "printf 'a\\r\\nb' > data.txt" },
- { "id": "measure", "command": "wc -c data.txt" }
- ]
- }
- ```
- See [compiled MCP batch plans](docs/rfc-mcp-batch-plans.md) 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:
- ```bash
- 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](docs/rfc-bash-facade.md).
- ## 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`](docs/benchmark-deepseek-v4-pro.md) and
- [`docs/benchmark-ark-models.md`](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 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).
- | | fauxnix | Git Bash | WSL | Raw PowerShell |
- |---|---|---|---|---|
- | agent writes plain bash | ✓ | ✓ | ✓ | ✗ |
- | only needs Node (no bash toolchain / VM) | ✓ | ✗ | ✗ (VM, GBs) | ✓ |
- | native Windows filesystem & environment | ✓ | mostly | ✗ (9P bridge) | ✓ |
- | differential compatibility | 269/270 cases identical; limits below | GNU reference | GNU tools | different contracts |
- | CRLF / UTF-8 / GBK traps handled | ✓ | locale-dependent | ✓ | ✗ |
- **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](https://github.com/anthropics/claude-code/issues/73461) 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](docs/rfc-computer-use-windows.md)).
- ## 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`](docs/command-specs.md)
- is the exact list, coverage count, option table, and exclusion rationale; `fauxnix list --json`
- exposes the same per-command metadata. `find` stays unspec'd so predicates like `-name` still
- compile; `sed`/`awk`/`egrep` keep their command-specific parsers; `tar` remains native to
- `tar.exe` so supported bsdtar options reach the executable. Implemented GNU holes include
- `cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` / `head --lines` /
- `du --max-depth` / `env -u` / `ps -f` / `command -V` / `date --date=@SECONDS`.
- Plus shell syntax: pipes, `&&` / `||` / `;`, redirections (`> >> 2> 2>&1 < &>`, `/dev/null`),
- quoting, `$VAR` `$1` `$#` `"$@"` `set --` `shift`, `${name:-word}` `${name//pat/str}`
- `${name:off:len}` `${name[n]}` `${#name[@]}`, `A=(x y z)` array assignment, `$(...)` command
- substitution, `VAR=x cmd` prefixes, `~` expansion, and POSIX-style path normalization
- (`/tmp`, `/d/foo` → `D:\foo`). Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious,
- 127 command not found, 124 timeout.
- Unknown commands (git, node, npm, python, cargo, gh, docker, ...) are **passed through natively**
- with argv-style quoting. Windows `.cmd`/`.bat` shims necessarily pass through `cmd.exe`; fauxnix
- preserves its supported punctuation and fails loudly for `%`, embedded double quotes, NUL, and
- line breaks rather than passing a different argument.
- ## How it works
- ```
- bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ selected PowerShell
- │
- agent ◀── GNU-style output, bash-style errors ◀── UTF-8 framed host protocol ◀┘
- ```
- - **Deterministic translation, zero LLM calls** at runtime.
- - Each command maps to a generator that emits a self-contained PowerShell block honoring the
- "Fauxnix contract": string-per-line stdout, `[Console]::Error.WriteLine` for bash-style
- stderr, `$script:fx_exit` for exit codes, `$input` for stdin.
- - The executor wraps every script with UTF-8 enforcement, decodes native output at the process
- boundary (UTF-8 by default or GBK(936) in `ansi` mode), strips CLIXML serialization and
- PowerShell noise from stderr, and rewrites common PowerShell errors (including zh-CN locale
- messages) into bash phrasing. File reads are always sniffed per file (UTF-8 strict → GBK
- fallback), so grep/sed/awk over GBK files works in either mode.
- - Scripts run via `-EncodedCommand` (UTF-16LE) and transparently fall back to a temp `.ps1` file
- when the 32 KB command-line limit would be exceeded.
- PowerShell 7 is an opt-in, CI-tested tier: set `FAUXNIX_PS=pwsh` before starting fauxnix or its
- MCP harness. The default is Windows PowerShell 5.1; invalid values fail loudly rather than
- falling back. See [PowerShell 7 support](docs/powershell-7.md).
- ## Known deviations (honest list)
- fauxnix optimizes for the commands agents actually run. Documented deviations:
- - `X=1` standalone assignments follow `export` semantics (one session-wide environment; bash's
- shell-var vs exported-var distinction does not exist), and a same-segment prefix is visible to
- `$VAR` inside the command's own words (`Z=in [[ $Z == in ]]` is true here, false in bash where
- word expansion precedes the temporary environment).
- - `yes` is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so
- an unbounded `yes | head` would hang.
- - `tail -f`, `eval`, `alias`, heredocs, `env -i`/`--ignore-environment`, background `&`, and
- output/fd redirects on a non-last pipeline stage are rejected with operation-specific,
- actionable error messages instead of misbehaving. Per-stage `<` remains supported.
- (`if/then/elif/else/fi`, `for x in ...`, `while`/`until`, `case ... esac` (`;;` only),
- backtick substitution, `command -v`, pipeline `read`, dotenv-style `source`, word-level
- `$((...))` arithmetic expansion, `A=(x y z)` arrays, and `${name//pat/str}` /
- `${name:off:len}` are supported.)
- - `command -v <builtin>` prints `/usr/bin/<name>` where bash prints the bare builtin name;
- exit codes and empty-result semantics match.
- - `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
- (as in Git Bash).
- - `ps aux` columns are approximations (no per-process CPU% accounting, USER shows `?`).
- - `gzip -c`/pipeline stdin is text-faithful, not byte-faithful; file-mode `gzip f` is byte-exact.
- - Gzip decompression and `gzip -t` use Node's strict streaming decoder, including
- every concatenated member. Incomplete streams and checksum errors fail without
- committing a destination or deleting the archive. Trailing non-gzip garbage is
- an error rather than GNU's warning. Text stdout is validated before emission and
- needs temporary disk space proportional to decoded size; `-t` discards output.
- Standalone translated scripts require supported `node.exe` on PATH. See the
- [strict gzip contract](docs/rfc-strict-gzip.md) for cancellation and spool limits.
- - `mv` replaces regular files only within one volume, without predeleting the
- destination. Cross-volume replacement, leaf reparse-point replacement, and
- replacing an existing empty directory fail explicitly with originals retained;
- `-f` does not bypass these limits. Existing-target `-n` still skips. Ordinary
- absent-target moves retain PowerShell behavior and are not transactional across
- volumes. Identity checks and rename are separate operations, not a race-proof
- transaction. See the [move contract](docs/rfc-safe-file-move.md).
- - `stat --printf` omits the implicit newline and interprets text escapes, including ASCII
- octal/hex escapes. Numeric escapes producing bytes `0x80`–`0xFF` are rejected before output;
- use literal Unicode text instead. NUL is preserved in direct output, text pipelines, and
- redirected files; command substitution retains fauxnix's existing text behavior rather
- than Bash's NUL-removal behavior.
- - A pipeline producing exactly one line, piped into `wc -l`, counts that line (bash would count 0
- if the producer omitted the trailing newline). `printf 'x' | md5sum` stays byte-exact.
- - `sed`/`awk` support the common subset; hold-space, labels, arrays, loops throw named
- "not supported" errors at translate time.
- For `awk` programs using `printf`, terminal and file-redirect output streams per formatted
- fragment. Pipeline and command-substitution output is coalesced into one text value to
- preserve adjacent fragments without adding separators. That intermediate value requires
- memory proportional to output size and is not capped by the caller's capture budget.
- - `curl`/`wget` refuse loopback/private/reserved addresses (localhost, 127.x, ::1, 10.x,
- 172.16–31.x, 192.168.x, 169.254.x) as a safety default for agent-driven HTTP.
- - **Native-tool pipelines vs encoding**: PS 5.1 has a single console-encoding knob, so piping
- localized admin tools (ipconfig, tasklist — GBK on zh-CN) and UTF-8-native dev tools (node,
- curl) cannot both decode cleanly mid-pipeline. Default favors UTF-8 dev tools; set
- `FAUXNIX_NATIVE_ENCODING=ansi` when your agents grep Chinese output of native Windows admin
- tools.
- ## Development
- ```powershell
- npm install
- npm test # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
- $env:FAUXNIX_PS = 'pwsh'; npm test # same suite through PowerShell 7
- npm run build
- npx tsx scratch/run.mjs "any bash command" # quick live check
- ```
- Differential vs Git Bash is locally opt-in (`FAUXNIX_DIFF_ORACLE=1`). The minimum-runtime
- Windows x64 / PowerShell 5.1 CI lane requires Git Bash and runs the 270-case primary corpus
- plus a separate 41-case supplementary corpus. Other lanes may skip these checks.
- The primary corpus currently matches 269/270 cases (99.6%); the remaining observed mismatch
- is the documented Git Bash empty-regex-alternative behavior. The historical 253-case result
- is not a same-corpus comparison. See [`test/differential/README.md`](test/differential/README.md).
- The primary gate remains at least 200 cases and 95% identity; the weekly oracle also runs
- from `.github/workflows/differential.yml`.
- Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (AST → PowerShell +
- executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
- `src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
- Roadmap: [docs/rfc-roadmap-to-1.0.md](docs/rfc-roadmap-to-1.0.md) — tracks, milestones, and the
- RFC process for proposing waves.
- ## Security
- Trust model, host protocol, kill semantics, network guard, and reporting:
- [SECURITY.md](SECURITY.md).
- ## License
- MIT © 20000419
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.