Fauxnix

What 20000419/fauxnix does

20000419/fauxnix provides a Windows-native command layer for AI agents that write bash. Instead of requiring a Bash runtime, it converts supported bash syntax and commands into PowerShell operations, executes them on the local Windows filesystem, and formats results to resemble GNU/Linux command-line behavior.

The package covers a broad subset of file management, text processing, process management, archives, and basic networking commands. Examples include ls, find, grep, wc, cp, mv, rm, chmod, stat, and kill. Commands that are outside the supported translation subset fail explicitly and identify the unsupported construct rather than producing a silent or approximate result. Native programs such as git, node, and npm pass through with argument quoting adapted for Windows.

How it works

The MCP entry point is started with fauxnix mcp over stdio. Its primary tool is named bash; the name can be changed with FAUXNIX_TOOL_NAME. Each call runs in a persistent session. Changes to cwd, exported or unset variables, OLDPWD, and positional parameters remain available to later calls, so the interaction resembles a logged-in shell rather than independent process launches.

For predetermined workflows, bash_batch accepts an ordered list of command steps. fauxnix compiles the complete plan before execution, runs it in one session, and returns a structured result for each step. Execution stops at the first nonzero exit by default.

Input and output handling includes UTF-8 and GBK file detection, GNU-like listings, bash-style error text, and coreutils-compatible exit codes. The implementation makes no runtime LLM calls.

Setup and configuration

Install the CLI globally with:

npm install -g fauxnix-cli

The runtime requires Windows, PowerShell 5.1 or newer, and Node.js 22.20.0 or newer. Start the MCP server with:

fauxnix mcp

The installer can add configurations for supported harnesses:

fauxnix install --claude
fauxnix install --codex
fauxnix install --opencode
fauxnix install --kimi
fauxnix install --qwen

Run fauxnix doctor to check encoding support, harness configuration, and an MCP round trip. Manual configuration uses the command fauxnix with the argument mcp.

Tools and capabilities

• Translate supported bash commands into native PowerShell execution.
• Preserve working directory, environment, exports, unset, cd -, and positional parameters between calls.
• Provide GNU-style output and bash-like errors on Windows.
• Detect UTF-8 and GBK files per file for text operations such as grep.
• Execute multi-step bash_batch plans with one MCP round trip.
• Pass native Windows commands through with argv quoting.
• Run directly from the CLI, including fauxnix "ls -la src" and fauxnix translate "...".

Limitations and notes

fauxnix translates a defined command and syntax subset rather than implementing a complete Bash shell. Unsupported constructs fail loudly, so workflows depending on arbitrary Bash features should be tested against the translator. Node.js 18 and 20 are unsupported for the v2 release.

The server uses a local stdio connection and executes commands on the Windows host. In Codex non-interactive codex exec mode, MCP calls are automatically denied by the approval layer unless approvals and sandbox restrictions are bypassed as described by the project configuration. The optional Claude Code native shell facade is experimental and separate from the MCP server.