Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/20000419--fauxnix/badge.svg)](/listings/20000419--fauxnix)

HTML

<a href="/listings/20000419--fauxnix"><img src="/api/listings/20000419--fauxnix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. # fauxnix
  2. [![CI](https://github.com/20000419/fauxnix/actions/workflows/ci.yml/badge.svg)](https://github.com/20000419/fauxnix/actions/workflows/ci.yml)
  3. [![npm version](https://img.shields.io/npm/v/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
  4. [![npm downloads](https://img.shields.io/npm/dt/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
  5. [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. [![20000419/fauxnix MCP server](https://glama.ai/mcp/servers/20000419/fauxnix/badges/score.svg)](https://glama.ai/mcp/servers/20000419/fauxnix)
  7. **Run Linux-style commands on Windows — natively, deterministically, no VM, no WSL.**
  8. fauxnix is a bash→PowerShell translation layer built for AI agents. Your agent keeps writing the
  9. bash it already knows (`ls -la | grep foo`, `find . -name '*.ts' | wc -l`, `kill -9 1234`), and
  10. fauxnix deterministically translates each command into PowerShell, executes it natively, and hands
  11. back output that looks like GNU/Linux: `ls -l` columns, bash-style error messages, coreutils exit
  12. codes, UTF-8/GBK handled automatically.
  13. One-command install for **Claude Code · Codex · OpenCode · Kimi Code · Qwen Code**, plus any MCP
  14. client. **109 translated commands · 1,469 automated tests · 270-case Git Bash differential
  15. corpus plus 41 supplementary checks · zero LLM calls at runtime.**
  16. This checkout is **v2.2.0**. See [migration and release notes](docs/releases/v2.0.0.md)
  17. for the Node.js requirement, changed file-operation contracts and verification limits.
  18. The npm badge and `@latest` examples show the published version until publication completes.
  19. ## Try it now — no install
  20. ```bash
  21. npx fauxnix-cli@latest "ls -la src | head -3"
  22. npx fauxnix-cli@latest translate "find . -name '*.log' -mtime +7 -delete"
  23. ```
  24. ![fauxnix demo](docs/assets/demo.svg)
  25. ```
  26. $ fauxnix "ls -la src | head -2"
  27. -rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
  28. -rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts
  29. $ fauxnix "cat nope.txt"
  30. cat: nope.txt: No such file or directory # not a PowerShell stack trace
  31. ```
  32. ## Connect your agent — one command
  33. ```bash
  34. npm install -g fauxnix-cli
  35. fauxnix install --claude # or --codex / --opencode / --kimi / --qwen
  36. fauxnix doctor # verifies encoding, harness config, and MCP round-trip
  37. ```
  38. Idempotent; prints exactly what changed. Manual configurations below if you prefer to edit
  39. config files yourself.
  40. > npm package name is `fauxnix-cli` (the `fauxnix` name on npm belongs to an unrelated 2015
  41. > websocket library); the installed command is `fauxnix`. Requires Windows with PowerShell 5.1+
  42. > (built-in) and Node.js ≥ 22.20.0.
  43. > Node 18/20 are unsupported in v2. Current Node 22/24 LTS patches are tested.
  44. > Published v1.0.0 retains its original metadata.
  45. <details>
  46. <summary><b>Manual config per harness</b></summary>
  47. `fauxnix install --<harness>` writes the **spawn-safe** form shown below: the absolute Node
  48. executable plus this installation's absolute entry. A bare `command: "fauxnix"` is an
  49. extension-less npm shim on Windows — MCP clients that spawn the server directly (CreateProcess)
  50. cannot execute it (#252). Shell-wrapping clients like Claude Code accept either form; the
  51. absolute form works everywhere.
  52. **Claude Code**
  53. ```bash
  54. claude mcp add fauxnix -- fauxnix mcp
  55. ```
  56. **Codex** (`~/.codex/config.toml` or `codex mcp add fauxnix -- fauxnix mcp`)
  57. ```toml
  58. [mcp_servers.fauxnix]
  59. command = 'C:\Program Files\nodejs\node.exe'
  60. args = ['C:\Users\<you>\AppData\Roaming\npm\node_modules\fauxnix-cli\dist\index.js', 'mcp']
  61. ```
  62. Note: in non-interactive `codex exec` mode, MCP tool calls are auto-denied by the approval
  63. layer; pass `--dangerously-bypass-approvals-and-sandbox` (or run interactively and approve
  64. once).
  65. **OpenCode** (`opencode.json`)
  66. ```json
  67. {
  68. "mcp": {
  69. "fauxnix": {
  70. "type": "local",
  71. "command": ["C:\\Program Files\\nodejs\\node.exe", "C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\fauxnix-cli\\dist\\index.js", "mcp"]
  72. }
  73. }
  74. }
  75. ```
  76. **Kimi Code** — MCP servers live in a JSON file, not the TOML config: `~/.kimi-code/mcp.json`
  77. ```json
  78. {
  79. "mcpServers": {
  80. "fauxnix": {
  81. "command": "C:\\Program Files\\nodejs\\node.exe",
  82. "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\fauxnix-cli\\dist\\index.js", "mcp"]
  83. }
  84. }
  85. }
  86. ```
  87. **Qwen Code** (`~/.qwen/settings.json`)
  88. ```bash
  89. fauxnix install --qwen
  90. ```
  91. The installer preserves the rest of `settings.json` and writes the same absolute launcher.
  92. See [the Qwen example](docs/examples/qwen.md) for the generated JSON shape.
  93. **Any MCP client** — stdio server: `fauxnix mcp`. The tool name is `bash` (override with
  94. `FAUXNIX_TOOL_NAME`). The tool description already teaches the model the supported subset, so no
  95. system-prompt changes are required.
  96. Copy-paste quickstarts with a 10-command smoke test per harness: [`docs/examples/`](docs/examples/)
  97. </details>
  98. The MCP session persists `cwd`, environment variables, `export`/`unset`, `cd -`/OLDPWD, and
  99. positional parameters (`set --` / `$1` / `"$@"`) across tool calls — it behaves like a logged-in
  100. shell, not a stateless `exec`. `$0` is the MCP tool name, not a Windows path.
  101. For workflows whose commands are already known, the MCP server also exposes `bash_batch`: it
  102. compiles every step before execution, runs the plan atomically in one session, and returns one
  103. structured result per step in a single MCP round trip (stops on first nonzero exit by default).
  104. ```json
  105. {
  106. "steps": [
  107. { "id": "write", "command": "printf 'a\\r\\nb' > data.txt" },
  108. { "id": "measure", "command": "wc -c data.txt" }
  109. ]
  110. }
  111. ```
  112. See [compiled MCP batch plans](docs/rfc-mcp-batch-plans.md) for timeout, budget, cancellation,
  113. and preflight semantics.
  114. ### Experimental: native shell facade
  115. Point Claude Code's **built-in Bash tool** at fauxnix — no MCP sidecar, zero protocol round
  116. trips per command:
  117. ```bash
  118. fauxnix install --claude-shell # builds a fauxnix-backed bash.exe (~85 MB) and sets
  119. # CLAUDE_CODE_GIT_BASH_PATH; restart Claude Code after
  120. fauxnix doctor # reports the launcher status
  121. fauxnix install --claude-shell-off # restores the previous setting
  122. ```
  123. The launcher is a copy of your own node.exe with the facade bundle injected via Node SEA
  124. (experimental trade-off; the GA plan is a small prebuilt stub). It implements the bash argv
  125. contract (`bash -c`/`-lc`, `$0`/`$1` from trailing operands), adapts the harness's private
  126. command scaffolding (captured from a live session — payload execution, cwd markers, snapshot
  127. stubs), and always identifies itself via `--version`. The harness's own Bash approval flow
  128. governs runs. `fauxnix facade` also runs standalone. Details, security rules, and the protocol
  129. findings: [RFC — native shell facade](docs/rfc-bash-facade.md).
  130. ## Measured: your model is probably worse at PowerShell than you think
  131. Same model (DeepSeek-V4-Pro), same 5 tasks, three execution modes on one Windows machine —
  132. full data in [`docs/benchmark-deepseek-v4-pro.md`](docs/benchmark-deepseek-v4-pro.md) and
  133. [`docs/benchmark-ark-models.md`](docs/benchmark-ark-models.md):
  134. | | PowerShell | **fauxnix** | Git Bash |
  135. |---|---|---|---|
  136. | tool calls / unexpected errors | 14 / 9 | **7 / 0** | 4 / 0 |
  137. | time (T1–T4) | 163s | **66s** | 57s |
  138. Across 7 models on the Volcano Ark Coding Plan, the PowerShell-vs-fauxnix gap held for every
  139. model tested — worst case (kimi-k2-thinking): **3.1× slower with 24 error events** writing
  140. PowerShell vs zero errors through fauxnix. fauxnix lands within ~15% of the real-bash ceiling
  141. with no bash toolchain installed.
  142. ## Why
  143. LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so
  144. models on Windows often produce "looks right, doesn't run" commands (wrong quoting, `curl` that
  145. isn't curl, mojibake from codepage mismatches, inscrutable `CategoryInfo` error dumps).
  146. | | fauxnix | Git Bash | WSL | Raw PowerShell |
  147. |---|---|---|---|---|
  148. | agent writes plain bash | ✓ | ✓ | ✓ | ✗ |
  149. | only needs Node (no bash toolchain / VM) | ✓ | ✗ | ✗ (VM, GBs) | ✓ |
  150. | native Windows filesystem & environment | ✓ | mostly | ✗ (9P bridge) | ✓ |
  151. | differential compatibility | 269/270 cases identical; limits below | GNU reference | GNU tools | different contracts |
  152. | CRLF / UTF-8 / GBK traps handled | ✓ | locale-dependent | ✓ | ✗ |
  153. **If Git Bash already works for you, keep it** — we literally use it as our differential-testing
  154. oracle. fauxnix is for when you can't or don't want to ship one: agent fleets where the bash
  155. toolchain drifts or isn't detected (the [Windows ARM64 Git-Bash detection
  156. failure](https://github.com/anthropics/claude-code/issues/73461) is a live example), CI runners,
  157. locked-down machines, or anywhere a single `npm install -g` is easier than a toolchain.
  158. fauxnix takes the third road: **translate, don't emulate**. A large, high-value subset of the
  159. Linux command line — file ops, text processing, process management, archives, networking basics —
  160. maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and *fails loudly
  161. and helpfully* on what it can't translate, so the agent never gets silently-wrong results.
  162. That matters as labs train computer-use agents on Mac fleets — the agent keeps writing bash;
  163. fauxnix makes the Windows box answer like the box the agent was trained on
  164. ([RFC: computer-use parity](docs/rfc-computer-use-windows.md)).
  165. ## What's translated
  166. 109 commands, output-matched against real GNU coreutils on Windows (Git Bash) during development:
  167. - **files**: `ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff`
  168. - **text filters**: `grep egrep sed awk sort uniq cut tr` — sed/awk scripts are parsed while
  169. preparing an executable plan (unsupported constructs throw named errors, never silently
  170. misbehave)
  171. - **text I/O**: `echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs`
  172. - **shell/system**: `cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami
  173. id groups date uname hostname uptime free nproc clear true false test [ [[ : pushd popd dirs sudo
  174. timeout man history less more source . eval exit alias set shift`
  175. - **network**: `curl wget ping netstat ss ip ifconfig nslookup dig host`
  176. - **archives**: `tar gzip gunzip zcat zip unzip`
  177. The curated **agent-daily 60** carry a `CommandSpec`: unknown options fail with a GNU-style
  178. usage error instead of being ignored. The generated [`docs/command-specs.md`](docs/command-specs.md)
  179. is the exact list, coverage count, option table, and exclusion rationale; `fauxnix list --json`
  180. exposes the same per-command metadata. `find` stays unspec'd so predicates like `-name` still
  181. compile; `sed`/`awk`/`egrep` keep their command-specific parsers; `tar` remains native to
  182. `tar.exe` so supported bsdtar options reach the executable. Implemented GNU holes include
  183. `cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` / `head --lines` /
  184. `du --max-depth` / `env -u` / `ps -f` / `command -V` / `date --date=@SECONDS`.
  185. Plus shell syntax: pipes, `&&` / `||` / `;`, redirections (`> >> 2> 2>&1 < &>`, `/dev/null`),
  186. quoting, `$VAR` `$1` `$#` `"$@"` `set --` `shift`, `${name:-word}` `${name//pat/str}`
  187. `${name:off:len}` `${name[n]}` `${#name[@]}`, `A=(x y z)` array assignment, `$(...)` command
  188. substitution, `VAR=x cmd` prefixes, `~` expansion, and POSIX-style path normalization
  189. (`/tmp`, `/d/foo` → `D:\foo`). Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious,
  190. 127 command not found, 124 timeout.
  191. Unknown commands (git, node, npm, python, cargo, gh, docker, ...) are **passed through natively**
  192. with argv-style quoting. Windows `.cmd`/`.bat` shims necessarily pass through `cmd.exe`; fauxnix
  193. preserves its supported punctuation and fails loudly for `%`, embedded double quotes, NUL, and
  194. line breaks rather than passing a different argument.
  195. ## How it works
  196. ```
  197. bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ selected PowerShell
  198. │
  199. agent ◀── GNU-style output, bash-style errors ◀── UTF-8 framed host protocol ◀┘
  200. ```
  201. - **Deterministic translation, zero LLM calls** at runtime.
  202. - Each command maps to a generator that emits a self-contained PowerShell block honoring the
  203. "Fauxnix contract": string-per-line stdout, `[Console]::Error.WriteLine` for bash-style
  204. stderr, `$script:fx_exit` for exit codes, `$input` for stdin.
  205. - The executor wraps every script with UTF-8 enforcement, decodes native output at the process
  206. boundary (UTF-8 by default or GBK(936) in `ansi` mode), strips CLIXML serialization and
  207. PowerShell noise from stderr, and rewrites common PowerShell errors (including zh-CN locale
  208. messages) into bash phrasing. File reads are always sniffed per file (UTF-8 strict → GBK
  209. fallback), so grep/sed/awk over GBK files works in either mode.
  210. - Scripts run via `-EncodedCommand` (UTF-16LE) and transparently fall back to a temp `.ps1` file
  211. when the 32 KB command-line limit would be exceeded.
  212. PowerShell 7 is an opt-in, CI-tested tier: set `FAUXNIX_PS=pwsh` before starting fauxnix or its
  213. MCP harness. The default is Windows PowerShell 5.1; invalid values fail loudly rather than
  214. falling back. See [PowerShell 7 support](docs/powershell-7.md).
  215. ## Known deviations (honest list)
  216. fauxnix optimizes for the commands agents actually run. Documented deviations:
  217. - `X=1` standalone assignments follow `export` semantics (one session-wide environment; bash's
  218. shell-var vs exported-var distinction does not exist), and a same-segment prefix is visible to
  219. `$VAR` inside the command's own words (`Z=in [[ $Z == in ]]` is true here, false in bash where
  220. word expansion precedes the temporary environment).
  221. - `yes` is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so
  222. an unbounded `yes | head` would hang.
  223. - `tail -f`, `eval`, `alias`, heredocs, `env -i`/`--ignore-environment`, background `&`, and
  224. output/fd redirects on a non-last pipeline stage are rejected with operation-specific,
  225. actionable error messages instead of misbehaving. Per-stage `<` remains supported.
  226. (`if/then/elif/else/fi`, `for x in ...`, `while`/`until`, `case ... esac` (`;;` only),
  227. backtick substitution, `command -v`, pipeline `read`, dotenv-style `source`, word-level
  228. `$((...))` arithmetic expansion, `A=(x y z)` arrays, and `${name//pat/str}` /
  229. `${name:off:len}` are supported.)
  230. - `command -v <builtin>` prints `/usr/bin/<name>` where bash prints the bare builtin name;
  231. exit codes and empty-result semantics match.
  232. - `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
  233. (as in Git Bash).
  234. - `ps aux` columns are approximations (no per-process CPU% accounting, USER shows `?`).
  235. - `gzip -c`/pipeline stdin is text-faithful, not byte-faithful; file-mode `gzip f` is byte-exact.
  236. - Gzip decompression and `gzip -t` use Node's strict streaming decoder, including
  237. every concatenated member. Incomplete streams and checksum errors fail without
  238. committing a destination or deleting the archive. Trailing non-gzip garbage is
  239. an error rather than GNU's warning. Text stdout is validated before emission and
  240. needs temporary disk space proportional to decoded size; `-t` discards output.
  241. Standalone translated scripts require supported `node.exe` on PATH. See the
  242. [strict gzip contract](docs/rfc-strict-gzip.md) for cancellation and spool limits.
  243. - `mv` replaces regular files only within one volume, without predeleting the
  244. destination. Cross-volume replacement, leaf reparse-point replacement, and
  245. replacing an existing empty directory fail explicitly with originals retained;
  246. `-f` does not bypass these limits. Existing-target `-n` still skips. Ordinary
  247. absent-target moves retain PowerShell behavior and are not transactional across
  248. volumes. Identity checks and rename are separate operations, not a race-proof
  249. transaction. See the [move contract](docs/rfc-safe-file-move.md).
  250. - `stat --printf` omits the implicit newline and interprets text escapes, including ASCII
  251. octal/hex escapes. Numeric escapes producing bytes `0x80`–`0xFF` are rejected before output;
  252. use literal Unicode text instead. NUL is preserved in direct output, text pipelines, and
  253. redirected files; command substitution retains fauxnix's existing text behavior rather
  254. than Bash's NUL-removal behavior.
  255. - A pipeline producing exactly one line, piped into `wc -l`, counts that line (bash would count 0
  256. if the producer omitted the trailing newline). `printf 'x' | md5sum` stays byte-exact.
  257. - `sed`/`awk` support the common subset; hold-space, labels, arrays, loops throw named
  258. "not supported" errors at translate time.
  259. For `awk` programs using `printf`, terminal and file-redirect output streams per formatted
  260. fragment. Pipeline and command-substitution output is coalesced into one text value to
  261. preserve adjacent fragments without adding separators. That intermediate value requires
  262. memory proportional to output size and is not capped by the caller's capture budget.
  263. - `curl`/`wget` refuse loopback/private/reserved addresses (localhost, 127.x, ::1, 10.x,
  264. 172.16–31.x, 192.168.x, 169.254.x) as a safety default for agent-driven HTTP.
  265. - **Native-tool pipelines vs encoding**: PS 5.1 has a single console-encoding knob, so piping
  266. localized admin tools (ipconfig, tasklist — GBK on zh-CN) and UTF-8-native dev tools (node,
  267. curl) cannot both decode cleanly mid-pipeline. Default favors UTF-8 dev tools; set
  268. `FAUXNIX_NATIVE_ENCODING=ansi` when your agents grep Chinese output of native Windows admin
  269. tools.
  270. ## Development
  271. ```powershell
  272. npm install
  273. npm test # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
  274. $env:FAUXNIX_PS = 'pwsh'; npm test # same suite through PowerShell 7
  275. npm run build
  276. npx tsx scratch/run.mjs "any bash command" # quick live check
  277. ```
  278. Differential vs Git Bash is locally opt-in (`FAUXNIX_DIFF_ORACLE=1`). The minimum-runtime
  279. Windows x64 / PowerShell 5.1 CI lane requires Git Bash and runs the 270-case primary corpus
  280. plus a separate 41-case supplementary corpus. Other lanes may skip these checks.
  281. The primary corpus currently matches 269/270 cases (99.6%); the remaining observed mismatch
  282. is the documented Git Bash empty-regex-alternative behavior. The historical 253-case result
  283. is not a same-corpus comparison. See [`test/differential/README.md`](test/differential/README.md).
  284. The primary gate remains at least 200 cases and 95% identity; the weekly oracle also runs
  285. from `.github/workflows/differential.yml`.
  286. Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (AST → PowerShell +
  287. executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
  288. `src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
  289. Roadmap: [docs/rfc-roadmap-to-1.0.md](docs/rfc-roadmap-to-1.0.md) — tracks, milestones, and the
  290. RFC process for proposing waves.
  291. ## Security
  292. Trust model, host protocol, kill semantics, network guard, and reporting:
  293. [SECURITY.md](SECURITY.md).
  294. ## License
  295. MIT © 20000419

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.