20000419/fauxnix

fauxnix – Bash‑to‑PowerShell bridge for AI agents

What it does

• Provides a deterministic, zero‑LLM translation layer that lets large‑language‑model (LLM) agents write ordinary Linux‑style bash commands on a Windows machine.
• The tool parses a subset of bash (109 commands + common shell syntax), converts the command to an equivalent PowerShell script, runs it natively, and returns output that looks exactly like GNU coreutils (same column layout, error messages, exit codes, UTF‑8 handling).
• It ships as an npm package (fauxnix-cli) and runs on any Windows with PowerShell 5.1+ and Node ≥ 18 – no VM, no WSL, no extra binaries.

Why it matters for AI

• LLM agents are trained mainly on bash; on Windows they often produce commands that fail in PowerShell because of quoting, encoding, or missing utilities.
• By translating bash to PowerShell on the fly, fauxnix lets agents keep using the language they know while still executing correctly on Windows, improving reliability for code‑generation assistants (Claude Code, Codex, OpenCode, Kimi Code, Qwen Code) and any MCP‑compatible client.

Key features

• One‑command install for the major LLM‑coding assistants (fauxnix install --claude, etc.) and a generic fauxnix mcp server for custom agents.
• MCP session persistence – the server remembers the current directory, environment variables, and positional parameters across calls, mimicking a real interactive shell.
• Batch mode – agents can send a list of steps that are compiled and executed atomically, returning a structured result for each step.
• Extensive test coverage – 400+ automated tests and a 253‑case differential corpus verified against real GNU coreutils on Git Bash.
• Performance – benchmarks show roughly half the tool‑call errors and up to a 2.5× speed‑up compared with raw PowerShell for the same tasks.
• Supported command set includes core file utilities (ls, cp, rm, find), text processing (grep, sed, awk, sort), shell built‑ins (cd, export, set), networking (curl, wget, ping), and archive tools (tar, zip).
• Graceful failures – unsupported constructs (e.g., background &, heredocs, full eval) raise clear, GNU‑style error messages instead of silently misbehaving.

How it works

1. Parser – a lightweight bash‑subset parser builds an AST.
2. Translator – the AST is turned into a self‑contained PowerShell script that follows the “Fauxnix contract” (line‑by‑line stdout, error stream, exit code).
3. Executor – the script runs via PowerShell (-EncodedCommand or a temporary .ps1 file) with UTF‑8 enforcement and output post‑processing to strip PowerShell‑specific noise.
4. MCP server – exposes the tool as an MCP service (fauxnix mcp) that agents can call using the standard model‑code‑protocol.

Installation & quick start

# Run a single command without installing
npx fauxnix-cli@latest "ls -la src | head -3"

# Install globally and hook into an LLM assistant
npm install -g fauxnix-cli
fauxnix install --claude   # or --codex, --kimi, --qwen

The installed fauxnix command can then be used directly or via the MCP server.

Limitations & known deviations

• Variable assignments behave like export (no distinction between shell‑local and exported variables).
• Certain bash features are deliberately unsupported (e.g., yes is capped, tail -f, background &).
• chmod only handles the read‑only bit; chown is a no‑op on Windows.
• Some output nuances (e.g., ps aux column values) are approximations.

Security The repository includes a SECURITY.md describing the trust model, network guard, and reporting process.

License MIT © 20000419.

---

Fauxnix lets AI agents keep speaking the language they were trained on—bash—while running safely and efficiently on native Windows.