fauxnix

Führen Sie Linux-ähnliche Befehle unter Windows aus — nativ, deterministisch, ohne VM und ohne WSL.

fauxnix ist eine Bash→PowerShell-Übersetzungsschicht für KI-Agenten. Ihr Agent schreibt weiterhin das Bash, das er bereits kennt (ls -la | grep foo, find . -name '*.ts' | wc -l, kill -9 1234), und fauxnix übersetzt jeden Befehl deterministisch in PowerShell, führt ihn nativ aus und liefert Ausgaben, die wie GNU/Linux aussehen: ls -l-Spalten, Bash-artige Fehlermeldungen, Coreutils-Exit-Codes, UTF-8/GBK automatisch behandelt.

npm install -g fauxnix-cli    # then point any MCP harness at `fauxnix mcp`

$ 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

Gemessen: Ihr Modell ist wahrscheinlich schlechter in PowerShell, als Sie denken

Gleiches Modell (DeepSeek-V4-Pro), gleiche 5 Aufgaben, drei Ausführungsmodi auf einem Windows-Rechner — vollständige Daten in docs/benchmark-deepseek-v4-pro.md und `docs/benchmark-ark-models.md:

Über 7 Modelle im Volcano Ark Coding Plan hinweg bestand die PowerShell-vs-fauxnix-Lücke bei jedem getesteten Modell — extremer Fall (kimi-k2-thinking): 3,1× langsamer mit 24 Fehlerereignissen beim Schreiben von PowerShell gegenüber null Fehlern durch fauxnix. fauxnix liegt ohne installierte Bash-Toolchain innerhalb von ~15 % der echten Bash-Obergrenze.

Related MCP server: wmux

Warum

LLM-Agenten sind bei Bash deutlich besser als bei PowerShell — Bash dominiert die Trainingsdaten, daher erzeugen Modelle unter Windows oft Befehle, die „richtig aussehen, aber nicht laufen“ (falsche Quotierung, curl, das kein curl ist, Mojibake durch Codepage-Konflikte, unergründliche CategoryInfo-Fehlerausgaben). Bestehende Lösungen sind entweder eine vollständige VM (WSL — schwer, falsches Dateisystem, separate Umgebung) oder einfache Shell-Wrapper (immer noch PowerShell darunter).

fauxnix geht den dritten Weg: übersetzen, nicht emulieren. Eine große, wertvolle Teilmenge der Linux-Kommandozeile — Dateioperationen, Textverarbeitung, Prozessverwaltung, Archive, Netzwerk-Grundlagen — bildet sich sauber auf PowerShell + .NET ab. fauxnix implementiert diese Teilmenge getreu und scheitert laut und hilfreich bei dem, was es nicht übersetzen kann, sodass der Agent nie stillschweigend falsche Ergebnisse erhält.

Installation

npm install -g fauxnix-cli

Oder aus dem Quellcode:

git clone https://github.com/20000419/fauxnix && cd fauxnix && npm install -g .

Der npm-Paketname ist fauxnix-cli (der Name fauxnix auf npm gehört zu einer nicht verwandten Websocket-Bibliothek von 2015); der installierte Befehl ist weiterhin fauxnix.

Erfordert: Windows mit PowerShell 5.1+ (integriert) und Node.js ≥ 18.

Schnellstart

# one-off commands
fauxnix "ls -la"
fauxnix "grep -rn TODO src | wc -l"
fauxnix "cat log.txt | grep -i error | sort | uniq -c"

# see what a command becomes (great for debugging / learning PS)
fauxnix translate "find . -name '*.log' -mtime +7 -delete"

# check your environment
fauxnix check

# run the MCP stdio server (what agent harnesses connect to)
fauxnix mcp

Unbekannte Befehle (git, node, npm, python, cargo, gh, docker, ...) werden nativ durchgereicht mit argv-artiger Quotierung — kein erneutes Parsen von Strings, keine Quotierungsfehler.

Verwendung mit Ihrer Agent-Integration

fauxnix enthält einen MCP-stdio-Server, der ein bash-Tool bereitstellt (sowie fauxnix_translate und fauxnix_session). Richten Sie eine beliebige MCP-fähige Integration darauf aus:

Claude Code

claude mcp add fauxnix -- fauxnix mcp

Codex (~/.codex/config.toml oder codex mcp add fauxnix -- fauxnix mcp)

[mcp_servers.fauxnix]
command = "fauxnix"
args = ["mcp"]

Hinweis: Im nicht-interaktiven codex exec-Modus werden MCP-Tool-Aufrufe von der Genehmigungsebene automatisch abgelehnt; übergeben Sie --dangerously-bypass-approvals-and-sandbox (oder führen Sie es interaktiv aus und genehmigen Sie einmal).

OpenCode (opencode.json)

{
  "mcp": {
    "fauxnix": { "type": "local", "command": ["fauxnix", "mcp"] }
  }
}

Kimi Code — anders als bei den anderen leben MCP-Server in einer JSON-Datei, nicht in der TOML-Konfiguration: ~/.kimi-code/mcp.json

{
  "mcpServers": {
    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
  }
}

Beliebiger MCP-Client — Stdio-Server: fauxnix mcp. Der Tool-Name ist bash (überschreibbar mit FAUXNIX_TOOL_NAME). Die Tool-Beschreibung vermittelt dem Modell bereits die unterstützte Teilmenge, daher sind keine Änderungen am System-Prompt erforderlich.

Die MCP-Sitzung bleibt über Tool-Aufrufe hinweg bestehen: cwd, Umgebungsvariablen, export/unset und cd -/OLDPWD — sie verhält sich wie eine angemeldete Shell, nicht wie ein zustandsloses exec.

Was übersetzt wird

~105 Befehle, alle während der Entwicklung gegen echte GNU-Coreutils unter Windows (Git Bash) abgeglichen:

• Dateien: ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff

• Textfilter: grep egrep sed awk sort uniq cut tr — sed/awk-Skripte werden zur Übersetzungszeit geparst (nicht unterstützte Konstrukte werfen benannte Fehler, verhalten sich nie stillschweigend falsch)

• Text-E/A: 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

• Netzwerk: curl wget ping netstat ss ip ifconfig nslookup dig host

• Archive: tar gzip gunzip zcat zip unzip

Plus Shell-Syntax: Pipes, && / || / ;, Umleitungen (> >> 2> 2>&1 < &>, /dev/null), Quotierung, $VAR $(...)-Befehlsersetzung, VAR=x cmd-Präfixe, ~-Erweiterung und POSIX-artige Pfadnormalisierung (/tmp, /d/foo → D:\foo).

Exit-Codes folgen den Bash-Konventionen: 0 ok, 1 Fehler, 2 Verwendung/schwerwiegend, 127 Befehl nicht gefunden, 124 Timeout.

So funktioniert es

bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ powershell.exe
                                                                              │
agent ◀── GNU-style output, bash-style errors ◀── decoder (UTF-8 → GBK fallback) ◀┘

• Deterministische Übersetzung, null LLM-Aufrufe zur Laufzeit.

• Jeder Befehl wird auf einen Generator abgebildet, der einen eigenständigen PowerShell-Block erzeugt, der den „Fauxnix-Vertrag“ einhält: eine Zeichenkette pro Zeile auf stdout, [Console]::Error.WriteLine für Bash-artiges stderr, $script:fx_exit für Exit-Codes, $input für stdin.

• Der Executor umhüllt jedes Skript mit UTF-8-Erzwingung ([Console]::OutputEncoding, $OutputEncoding, chcp 65001), dekodiert die Ausgabe als strenges UTF-8 mit einem GBK(936)-Fallback für alte native Tools, entfernt CLIXML-Serialisierung und PowerShell-Rauschen aus stderr und schreibt häufige PowerShell-Fehler (einschließlich zh-CN-Gebietsschema-Meldungen) in Bash-Formulierung um.

• Skripte laufen über -EncodedCommand (UTF-16LE) und fallen transparent auf eine temporäre .ps1-Datei zurück, wenn das 32-KB-Kommandozeilenlimit überschritten würde.

Bekannte Abweichungen (ehrliche Liste)

fauxnix ist auf die Befehle optimiert, die Agenten tatsächlich ausführen. Dokumentierte Abweichungen:

• X=1-Einzelzuweisungen folgen der export-Semantik (eine sitzungsweite Umgebung; die Unterscheidung von Bash zwischen Shell-Variablen und exportierten Variablen existiert nicht), und ein Präfix im selben Segment ist für $VAR innerhalb der eigenen Wörter des Befehls sichtbar (Z=in [[ $Z == in ]] ist hier wahr, in Bash falsch, wo die Worterweiterung vor der temporären Umgebung erfolgt).

• yes ist auf 65.536 Zeilen begrenzt — PS-5.1-Pipelines können vorgeschaltete Produzenten nicht zum Stoppen auffordern, daher würde ein unbegrenztes yes | head hängen bleiben.

• tail -f, source, eval, alias, Here-Dokumente, Backticks, Shell-Kontrollfluss (if/for/while) und Hintergrund-& werden mit umsetzbaren Fehlermeldungen abgelehnt, statt sich falsch zu verhalten.

• chmod bildet nur das Schreibschutz-Bit ab; Ausführungsbits sind unter Windows wirkungslos. chown ist ein stiller No-op (wie in Git Bash).

• ps aux-Spalten sind Näherungswerte (keine CPU-% pro Prozess, USER zeigt ?).

• gzip -c/Pipeline-Stdin ist texttreu, nicht bytetreu; Dateimodus gzip f ist bytegenau.

• Eine Pipeline, die genau eine Zeile erzeugt und in wc -l eingespeist wird, zählt diese Zeile (Bash würde 0 zählen, wenn der Produzent das abschließende Newline weggelassen hat). printf 'x' | md5sum bleibt bytegenau.

• sed/awk unterstützen die gängige Teilmenge; Hold-Space, Marken, Arrays und Schleifen werfen zur Übersetzungszeit benannte „not supported“-Fehler.

• curl/wget lehnen Loopback-/private/reservierte Adressen ab (localhost, 127.x, ::1, 10.x, 172.16–31.x, 192.168.x, 169.254.x) als Sicherheitsstandard für agentengesteuertes HTTP.

• Native-Tool-Pipelines vs. Kodierung: Die PS 5.1 hat nur einen Konsolen-Kodierungsregler, daher können lokalisierte Admin-Tools (ipconfig, tasklist — GBK auf zh-CN) und UTF-8-native Dev- Tools (node, curl) nicht beide mitten in der Pipeline sauber dekodiert werden. Standardmäßig werden UTF-8-Dev- Tools bevorzugt; setzen Sie FAUXNIX_NATIVE_ENCODING=ansi, wenn Ihre Agenten chinesische Ausgaben nativer Windows-Admin-Tools durchsuchen. Datei-Lesevorgänge werden immer pro Datei erkannt (strenges UTF-8 → GBK-Fallback), daher funktioniert grep/sed/awk über GBK-Dateien in beiden Modi — im Gegensatz zu Git Bash, das nur die Kodierung abgleicht, die sein Gebietsschema annimmt.

Entwicklung

npm install
npm test          # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
npm run build
npx tsx scratch/run.mjs "any bash command"   # quick live check

Architektur-Übersicht: src/parser.ts (Bash-Teilmenge → AST) · src/translator.ts (AST → PowerShell + Executor-Wrapper) · src/executor.ts (Spawning, Umleitungen, Sitzungspersistenz) · src/commands/*.ts (Befehlsgeneratoren pro Befehl) · src/mcp.ts (MCP-Server) · src/cli.ts.

Lizenz

MIT © 20000419