Skip to main content
Glama
deenesjakoruzh
20000419

fauxnix

by 20000419
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

fauxnix

CI npm version npm downloads license 20000419/fauxnix MCP server

Ejecuta comandos estilo Linux en Windows — de forma nativa, determinista, sin VM y sin WSL.

fauxnix es una capa de traducción bash→PowerShell diseñada para agentes de IA. Tu agente sigue escribiendo el bash que ya conoce (ls -la | grep foo, find . -name '*.ts' | wc -l, kill -9 1234), y fauxnix traduce deterministamente cada comando a PowerShell, lo ejecuta de forma nativa y devuelve una salida que parece GNU/Linux: columnas de ls -l, mensajes de error estilo bash, códigos de salida de coreutils, UTF-8/GBK manejados automáticamente.

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

fauxnix demo

$ 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

Medido: tu modelo probablemente es peor en PowerShell de lo que crees

Mismo modelo (DeepSeek-V4-Pro), mismas 5 tareas, tres modos de ejecución en una máquina Windows — datos completos en docs/benchmark-deepseek-v4-pro.md y docs/benchmark-ark-models.md:

PowerShell

fauxnix

Git Bash

llamadas a herramientas / errores inesperados

14 / 9

7 / 0

4 / 0

tiempo (T1–T4)

163s

66s

57s

En 7 modelos del Volcano Ark Coding Plan, la brecha PowerShell-vs-fauxnix se mantuvo en todos los modelos probados — el peor caso (kimi-k2-thinking): 3.1× más lento con 24 eventos de error escribiendo PowerShell frente a cero errores con fauxnix. fauxnix se sitúa dentro de ~15% del techo real de bash sin tener instalado un toolchain de bash.

Related MCP server: wmux

Por qué

Los agentes LLM son dramáticamente mejores en bash que en PowerShell — bash domina los datos de entrenamiento, por lo que los modelos en Windows a menudo producen comandos que "parecen correctos pero no funcionan" (comillas incorrectas, curl que no es curl, mojibake por desajustes de codepage, volcados de error incomprensibles de CategoryInfo). Las soluciones existentes son o una VM completa (WSL — pesado, sistema de archivos incorrecto, entorno separado) o simples wrappers de shell (siguen siendo PowerShell por debajo).

fauxnix toma el tercer camino: traducir, no emular. Un subconjunto grande y de alto valor de la línea de comandos de Linux — operaciones de archivos, procesamiento de texto, gestión de procesos, archivos comprimidos, conceptos básicos de red — se mapea limpiamente sobre PowerShell + .NET. fauxnix implementa ese subconjunto fielmente y falla de forma ruidosa y útil en lo que no puede traducir, para que el agente nunca obtenga resultados silenciosamente incorrectos.

Instalación

npm install -g fauxnix-cli

O desde el código fuente:

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

El nombre del paquete npm es fauxnix-cli (el nombre fauxnix en npm pertenece a una biblioteca websocket no relacionada de 2015); el comando instalado sigue siendo fauxnix.

Requiere: Windows con PowerShell 5.1+ (integrado) y Node.js ≥ 18.

Inicio rápido

# 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

Los comandos desconocidos (git, node, npm, python, cargo, gh, docker, ...) se pasan de forma nativa con comillas estilo argv — sin re-parseo de cadenas, sin errores de comillas.

Uso con tu plataforma de agente

fauxnix incluye un servidor MCP stdio que expone una herramienta bash (además de fauxnix_translate y fauxnix_session). Apunta cualquier plataforma compatible con MCP hacia él:

Claude Code

claude mcp add fauxnix -- fauxnix mcp

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

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

Nota: en modo no interactivo codex exec, las llamadas a herramientas MCP son denegadas automáticamente por la capa de aprobación; pasa --dangerously-bypass-approvals-and-sandbox (o ejecuta interactivamente y aprueba una vez).

OpenCode (opencode.json)

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

Kimi Code — a diferencia de los demás, los servidores MCP viven en un archivo JSON, no en la configuración TOML: ~/.kimi-code/mcp.json

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

Cualquier cliente MCP — servidor stdio: fauxnix mcp. El nombre de la herramienta es bash (anula con FAUXNIX_TOOL_NAME). La descripción de la herramienta ya enseña al modelo el subconjunto soportado, por lo que no se requieren cambios en el prompt del sistema.

La sesión MCP persiste cwd, variables de entorno, export/unset y cd -/OLDPWD entre llamadas a herramientas — se comporta como un shell con sesión iniciada, no como un exec sin estado.

Qué se traduce

~105 comandos, todos comparados en salida con los coreutils GNU reales en Windows (Git Bash) durante el desarrollo:

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

  • filtros de texto: grep egrep sed awk sort uniq cut tr — los scripts de sed/awk se analizan en tiempo de traducción (las construcciones no soportadas lanzan errores con nombre, nunca se comportan mal silenciosamente)

  • E/S de texto: echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs

  • shell/sistema: 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

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

  • archivos comprimidos: tar gzip gunzip zcat zip unzip

Además, sintaxis de shell: tuberías, && / || / ;, redirecciones (> >> 2> 2>&1 < &>, /dev/null), comillas, sustitución de comandos $VAR $(...), prefijos VAR=x cmd, expansión de ~, y normalización de rutas estilo POSIX (/tmp, /d/foo → D:\foo).

Los códigos de salida siguen las convenciones de bash: 0 ok, 1 fallo, 2 uso/grave, 127 comando no encontrado, 124 timeout.

Cómo funciona

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

  • Traducción determinista, cero llamadas LLM en tiempo de ejecución.

  • Cada comando se asigna a un generador que emite un bloque PowerShell autocontenido que respeta el "contrato Fauxnix": stdout línea por línea, [Console]::Error.WriteLine para stderr estilo bash, $script:fx_exit para códigos de salida, $input para stdin.

  • El ejecutor envuelve cada script con aplicación de UTF-8 ([Console]::OutputEncoding, $OutputEncoding, chcp 65001), decodifica la salida como UTF-8 estricto con un respaldo GBK(936) para herramientas nativas heredadas, elimina la serialización CLIXML y el ruido de PowerShell de stderr, y reescribe errores comunes de PowerShell (incluidos mensajes de locale zh-CN) en fraseo de bash.

  • Los scripts se ejecutan mediante -EncodedCommand (UTF-16LE) y caen transparentemente a un archivo .ps1 temporal cuando se excedería el límite de línea de comandos de 32 KB.

Desviaciones conocidas (lista honesta)

fauxnix optimiza para los comandos que los agentes realmente ejecutan. Desviaciones documentadas:

  • Las asignaciones independientes X=1 siguen la semántica de export (un entorno de sesión; la distinción de bash entre variable de shell y variable exportada no existe), y un prefijo del mismo segmento es visible para $VAR dentro de las propias palabras del comando (Z=in [[ $Z == in ]] es verdadero aquí, falso en bash donde la expansión de palabras precede al entorno temporal).

  • yes está limitado a 65,536 líneas — las tuberías de PS 5.1 no pueden señalar a los productores upstream que se detengan, por lo que un yes | head sin límite colgaría.

  • tail -f, eval, alias, heredocs, while/until/case, expansión aritmética $((...)) a nivel de palabra y & en segundo plano se rechazan con mensajes de error accionables en lugar de comportarse mal. (if/then/else/fi, for x in ..., sustitución con backticks, command -v, read en tuberías y source estilo dotenv están soportados.)

  • command -v <builtin> imprime /usr/bin/<name> donde bash imprime el nombre del builtin desnudo; los códigos de salida y la semántica de resultado vacío coinciden.

  • chmod mapea solo el bit de solo lectura; los bits de ejecución son no-ops en Windows. chown es un no-op silencioso (como en Git Bash).

  • Las columnas de ps aux son aproximaciones (sin contabilidad de CPU% por proceso, USER muestra ?).

  • gzip -c/stdin de tubería es fiel al texto, no fiel al byte; el modo archivo gzip f es exacto en bytes.

  • Una tubería que produce exactamente una línea, canalizada a wc -l, cuenta esa línea (bash contaría 0 si el productor omitiera el salto de línea final). printf 'x' | md5sum sigue siendo exacto en bytes.

  • sed/awk soportan el subconjunto común; hold-space, etiquetas, arrays, bucles lanzan errores con nombre "no soportado" en tiempo de traducción.

  • curl/wget rechazan direcciones loopback/privadas/reservadas (localhost, 127.x, ::1, 10.x, 172.16–31.x, 192.168.x, 169.254.x) como valor predeterminado de seguridad para HTTP impulsado por agentes.

  • Tuberías de herramientas nativas vs codificación: PS 5.1 tiene una única perilla de codificación de consola, por lo que canalizar herramientas administrativas localizadas (ipconfig, tasklist — GBK en zh-CN) y herramientas de desarrollo nativas UTF-8 (node, curl) no puede decodificar ambas limpiamente en medio de la tubería. El valor predeterminado favorece las herramientas de desarrollo UTF-8; establece FAUXNIX_NATIVE_ENCODING=ansi cuando tus agentes hagan grep de salida china de herramientas administrativas nativas de Windows. Las lecturas de archivos siempre se detectan por archivo (UTF-8 estricto → respaldo GBK), por lo que grep/sed/awk sobre archivos GBK funciona en cualquier modo — a diferencia de Git Bash, que solo coincide con la codificación que su locale asume.

Desarrollo

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

Mapa de arquitectura: src/parser.ts (subconjunto bash → AST) · src/translator.ts (AST → PowerShell + wrapper de ejecutor) · src/executor.ts (spawn, redirecciones, persistencia de sesión) · src/commands/*.ts (generadores por comando) · src/mcp.ts (servidor MCP) · src/cli.ts.

Licencia

MIT © 20000419

Available Tools

3 tools
bashA
Destructive

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 ~), command substitution $(...), and 108+ 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, while/until/case, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, and word-level $((...)) arithmetic expansion are supported.

CWD, environment variables, export/unset and cd 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. 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash-style command line to run
timeout_msNoTimeout in milliseconds (default 120000)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are sparse (destructiveHint true, openWorldHint true). The description adds extensive behavioral detail: deterministic translation to PowerShell, output formatting, encoding handling, persistence of CWD/env across calls, bash-style exit codes, structuredContent return, and platform requirements. This far exceeds what annotations alone offer, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Although the description is long, every sentence delivers critical information: execution method, supported/unsupported features, state persistence, exit codes, structured output, and platform constraints. It is well-structured with clear sections and front-loads the core purpose. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex tool (command execution with many edge cases), and the description covers all critical aspects: translation behavior, supported commands, unsupported constructs, state persistence, exit code semantics, structured content fields, and platform requirements. Even though no output schema is provided, the description explicitly enumerates the structuredContent fields. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both command and timeout_ms have descriptions). The description adds no extra parameter semantics beyond what the schema already states, such as the default timeout. Baseline of 3 is appropriate since the schema fully documents the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific action ('Execute a Linux/bash-style command') on a specific platform ('this Windows machine'). It clearly distinguishes itself from siblings like fauxnix_translate (presumably a translation utility) and fauxnix_session (session management). No ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists what is supported (pipes, redirections, variables, 108+ coreutils commands) and what is not (heredocs, while/until, env -i, background jobs). It also clarifies that unknown commands (git, node, etc.) are passed through natively. This gives concrete when-to-use and when-not-to-use guidance beyond the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fauxnix_sessionA
Idempotent

Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNo"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shellstatus

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains the effects of each action: status shows session state (cwd, tracked env keys), reset clears to a fresh shell. This enriches the idempotentHint=true and destructiveHint=false annotations by describing what actually changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence plus a brief action list. Every word is informative with no filler. Ideal conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one enum parameter, no output schema), the description fully covers the tool's purpose and behavior. The combination of description and schema leaves no meaningful gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a detailed enum description. The tool description reiterates the action names but adds no new semantic information beyond the schema. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool inspects or resets a persistent fauxnix shell session, with specific actions enumerated. This distinctly differentiates it from sibling tools bash (executing commands) and fauxnix_translate (translations).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (for session state inspection or reset) but does not explicitly contrast with sibling tools or provide when-not guidance. The clarity of purpose and sibling names indirectly guide selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fauxnix_translateA
Read-onlyIdempotent

Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash-style command line to translate (never executed)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds behavioral context by emphasizing 'WITHOUT executing it' and that the command is 'never executed', reinforcing safety beyond the annotations. This matches the bar for adding value beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core action and immediate caveat (no execution) in the first sentence, then stating the use case. Every sentence earns its place without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a single parameter, no output schema, and rich annotations (readOnly, idempotent, non-destructive), the description is complete enough. It explains the translation function, non-execution guarantee, and appropriate use case. The absence of return value detail is acceptable since there is no output schema to contradict, and the use case is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (1 parameter fully described in schema), so the baseline is 3. The description adds minimal parameter information beyond the schema (just reiterates 'bash-style command line'), but it does clarify that the command is never executed, which complements the schema description. No enum parameters exist to add further context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool translates a bash-style command into PowerShell without executing it, specifying the verb 'Translate' and the resource 'bash-style command'. It distinguishes itself from siblings like 'bash' or 'fauxnix_session' by highlighting its non-execution and translation-only purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states this is for learning or debugging what fauxnix does under the hood, providing clear context for when to use it. However, it does not specify when not to use it or mention alternatives, though the sibling 'bash' implies execution which contrasts with this tool's non-execution nature.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updates
    • First observedbash
    • First observedfauxnix_session
    • First observedfauxnix_translate
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: execute, translate without executing, and manage session state. There is no overlap in functionality, so an agent can unambiguously select the right tool.

Naming Consistency4/5

Two tools follow a 'fauxnix_' prefix pattern, but the primary tool is simply named 'bash', which breaks the convention. However, this is a deliberate choice for the main entry point and all names are clear and predictable.

Tool Count5/5

With only 3 tools, the server is tightly scoped to its core purpose: executing bash commands, providing translation for debugging, and managing the session. No redundant tools; each earns its place.

Completeness5/5

The toolset covers the full lifecycle of the domain: execution (bash), understanding/debugging (fauxnix_translate), and session management (fauxnix_session). There are no obvious gaps for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • COP Plug

    beepoo304
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to execute PowerShell commands, manage files, inspect projects, run Git operations, and monitor system information on Windows through a local MCP server.
    -

  • relaybridge

    maximyz3d
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides 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.
    8
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/20000419/fauxnix'

If you have feedback or need assistance with the MCP directory API, please join our Discord server