fauxnix
This server lets an AI agent run bash-style commands natively on Windows by deterministically translating them to PowerShell.
bash— execute one Linux/bash-style command (ls,grep,find,curl, pipes, redirections, variables, command substitution, etc.), returning GNU-like output and bash-style exit codes.bash_batch— run a preplanned multi-step workflow serially and atomically in one MCP round trip, compiling all steps upfront and reporting per-step results (stops on first error by default).fauxnix_translate— translate a bash command to the equivalent PowerShell script without executing it, for inspection/debugging.fauxnix_session— inspect or reset the persistent shell session (cwd, env, positional parameters, session id).Persistent state — cwd, environment variables,
export/unset,cd, and positional parameters persist across calls.Pass-through — unrecognized commands (
git,node,npm,python, etc.) execute natively on Windows.Bounded output — stdout/stderr are capped (256 KiB / 64 KiB by default; configurable in batches), with truncation marked.
Timeouts — per-command or per-batch timeout up to 10 minutes.
Windows-only backend — requires PowerShell 5.1+; otherwise returns exit code 127 with an actionable error.
Not supported — heredocs,
env -i, background jobs;sed/awkonly support a common subset.
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
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 traceRelated MCP server: wmux
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-tripIdempotent; prints exactly what changed. Manual configurations below if you prefer to edit config files yourself.
npm package name is
fauxnix-cli(thefauxnixname on npm belongs to an unrelated 2015 websocket library); the installed command isfauxnix. 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.
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
claude mcp add fauxnix -- fauxnix mcpCodex (~/.codex/config.toml or codex mcp add fauxnix -- fauxnix mcp)
[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)
{
"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
{
"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)
fauxnix install --qwenThe installer preserves the rest of settings.json and writes the same absolute launcher.
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 settingThe 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 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 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 difftext 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 xargsshell/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 shiftnetwork:
curl wget ping netstat ss ip ifconfig nslookup dig hostarchives:
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 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.WriteLinefor bash-style stderr,$script:fx_exitfor exit codes,$inputfor 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
ansimode), 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.ps1file 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.
Known deviations (honest list)
fauxnix optimizes for the commands agents actually run. Documented deviations:
X=1standalone assignments followexportsemantics (one session-wide environment; bash's shell-var vs exported-var distinction does not exist), and a same-segment prefix is visible to$VARinside the command's own words (Z=in [[ $Z == in ]]is true here, false in bash where word expansion precedes the temporary environment).yesis capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so an unboundedyes | headwould 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, pipelineread, dotenv-stylesource, 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.chmodmaps only the read-only bit; exec bits are no-ops on Windows.chownis a silent no-op (as in Git Bash).ps auxcolumns are approximations (no per-process CPU% accounting, USER shows?).gzip -c/pipeline stdin is text-faithful, not byte-faithful; file-modegzip fis byte-exact.Gzip decompression and
gzip -tuse 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;-tdiscards output. Standalone translated scripts require supportednode.exeon PATH. See the strict gzip contract for cancellation and spool limits.mvreplaces 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;-fdoes not bypass these limits. Existing-target-nstill 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.stat --printfomits the implicit newline and interprets text escapes, including ASCII octal/hex escapes. Numeric escapes producing bytes0x80–0xFFare 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' | md5sumstays byte-exact.sed/awksupport the common subset; hold-space, labels, arrays, loops throw named "not supported" errors at translate time. Forawkprograms usingprintf, 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/wgetrefuse 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=ansiwhen your agents grep Chinese output of native Windows admin tools.
Development
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 checkDifferential 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.
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 — tracks, milestones, and the RFC process for proposing waves.
Security
Trust model, host protocol, kill semantics, network guard, and reporting: SECURITY.md.
License
MIT © 20000419
Available Tools
4 toolsbashADestructive
Execute a Linux/bash-style command on this Windows machine.
Commands are deterministically translated to PowerShell and executed natively — no WSL or VM. Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME $1 $# "$@" ~), set -- / shift, array assignment A=(x y z), ${name[n]} ${#name[@]} ${name//pat/str} ${name:off:len}, command substitution $(...), and 109+ coreutils-style commands (., :, [, [[, alias, awk, base64, basename, cat, cd, chmod, chown, clear, command, cp, curl, cut, date...). Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting. Not supported: heredocs, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, while/until, case ... esac, and word-level $((...)) arithmetic expansion are supported. CWD, environment variables, export/unset, cd, and positional parameters (set -- / $1 / "$@") persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm. Efficiency: when two or more commands or verification steps are already known, prefer bash_batch once instead of making several bash calls. Keep separate calls only when the next command requires model interpretation of the previous output. For byte-exact work, measure with wc -c or stat -c %s instead of inferring CRLF byte counts from displayed text. MCP capture is bounded to 256 KiB stdout and 64 KiB stderr across the complete command list; larger output is marked truncated. Redirect larger artifacts to files. These transport-safe budgets include room for JSON escaping and duplicate text/structured fields. Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout, 130 cancelled). The tool also returns structuredContent (schemaVersion 1) with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId.
Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.
Inputs: command (required), timeout_ms.
bash_batchADestructive
Compile and execute a preplanned multi-step bash workflow in one MCP round trip.
Use this instead of repeated bash calls when the complete sequence is already known. Steps run serially and atomically in the same persistent session: later steps see cwd, environment, and files from earlier steps, while run/reset requests cannot interleave. Every command is parsed and translated before step 1 runs, and the result reports each step separately.
By default the batch stops after the first nonzero exit. Set stop_on_error=false only when later steps should still run. timeout_ms and both output limits apply to the whole batch, not once per step. Output defaults to 256 KiB stdout and 64 KiB stderr; redirect larger artifacts to files. Preflight performs no operand-file reads: use sed -e with inline script text instead of sed -f. If a later command depends on model interpretation of an earlier result, use separate bash calls instead. For byte counts, include wc -c or stat -c %s as a verification step rather than calculating CRLF bytes mentally.
Inputs: steps (required), timeout_ms, stop_on_error, stderr_limit_bytes, +1 more.
fauxnix_sessionAIdempotent
Inspect or reset the persistent fauxnix shell session (current directory, environment, positional count, session id). Actions: "status" (default) or "reset".
Inputs: action.
fauxnix_translateARead-onlyIdempotent
Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.
Inputs: command (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
bash and bash_batch overlap in purpose (both execute commands), but the descriptions give clear guidance on when to use each (batch for preplanned sequences, separate calls when model interpretation is needed). fauxnix_session and fauxnix_translate are clearly distinct. Only minor risk of misselection between the two execution tools.
Two naming families coexist: bare 'bash'/'bash_batch' (shared prefix, but no verb_noun form) and 'fauxnix_session'/'fauxnix_translate' (server-prefixed). The pattern is readable and not chaotic, but conventions are mixed rather than uniform.
Four tools is well-scoped for a shell-emulation server: execution, batched execution, session inspection, and translation each earn their place with no redundancy.
The surface covers execution, batch workflows, session status/reset, and translation introspection, which is solid lifecycle coverage for a shell proxy. Minor gap: no direct way to kill or interrupt a running process beyond reset, but core workflows are covered.
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseBqualityDmaintenanceHigh-performance MCP server giving AI agents advanced filesystem and automation capabilities on Windows, with 26 tools across file I/O, search, Git, process management, and more.262MIT
- AlicenseNot gradedqualityBmaintenanceA native Windows terminal multiplexer with MCP bridge for AI agents, enabling browser automation, multi-agent coordination, and terminal control.457MIT
- AlicenseNot gradedqualityBmaintenanceProvides a local Windows control plane for PowerShell and AI CLIs, exposing MCP tools for safe terminal sessions, bounded provider calls, routing, committees, and run receipts.4 npmMIT
- AlicenseAqualityCmaintenanceA Windows-native MCP gateway that lets any MCP-capable host orchestrate local coding-agent CLIs as external workers.11Apache 2.0