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

Запускайте команды в стиле Linux на Windows — нативно, детерминированно, без VM и без WSL.

fauxnix — это слой трансляции bash→PowerShell, созданный для AI-агентов. Ваш агент продолжает писать уже знакомый ему bash (ls -la | grep foo, find . -name '*.ts' | wc -l, kill -9 1234), а fauxnix детерминированно переводит каждую команду в PowerShell, выполняет её нативно и возвращает вывод, который выглядит как GNU/Linux: колонки ls -l, сообщения об ошибках в стиле bash, коды возврата coreutils, UTF-8/GBK обрабатываются автоматически.

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

Измерено: ваша модель, вероятно, хуже в PowerShell, чем вы думаете

Одна и та же модель (DeepSeek-V4-Pro), те же 5 задач, три режима выполнения на одной Windows-машине — полные данные в docs/benchmark-deepseek-v4-pro.md и docs/benchmark-ark-models.md:

PowerShell

fauxnix

Git Bash

вызовы инструментов / непредвиденные ошибки

14 / 9

7 / 0

4 / 0

время (T1–T4)

163s

66s

57s

На 7 моделях Volcano Ark Coding Plan разрыв между PowerShell и fauxnix сохранялся для каждой протестированной модели — худший случай (kimi-k2-thinking): в 3,1 раза медленнее с 24 ошибками при написании PowerShell против нуля ошибок через fauxnix. fauxnix попадает в ~15% от потолка реального bash без установленного bash-тулкита.

Related MCP server: wmux

Зачем

LLM-агенты значительно лучше работают с bash, чем с PowerShell — bash доминирует в обучающих данных, поэтому модели на Windows часто выдают команды, которые «выглядят правильно, но не работают» (неправильные кавычки, curl, который не является curl, кракозябры из-за несоответствия кодовых страниц, невнятные дампы ошибок CategoryInfo). Существующие решения — это либо полноценная VM (WSL — тяжёлая, неправильная файловая система, отдельное окружение), либо простые обёртки над оболочкой (всё равно PowerShell внутри).

fauxnix выбирает третий путь: переводить, а не эмулировать. Большое и ценное подмножество команд Linux — файловые операции, обработка текста, управление процессами, архивы, основы сетевого взаимодействия — чисто отображается на PowerShell + .NET. fauxnix реализует это подмножество точно и громко и понятно сообщает об ошибках на том, что не может перевести, чтобы агент никогда не получал молча неверные результаты.

Установка

npm install -g fauxnix-cli

Или из исходников:

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

Имя npm-пакета — fauxnix-cli (имя fauxnix на npm принадлежит несвязанной библиотеке websocket 2015 года); установленная команда по-прежнему называется fauxnix.

Требования: Windows с PowerShell 5.1+ (встроенный) и Node.js ≥ 18.

Быстрый старт

# 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

Неизвестные команды (git, node, npm, python, cargo, gh, docker, ...) передаются нативно с кавычками в стиле argv — без повторного разбора строк и ошибок кавычек.

Использование с вашим агентским харнессом

fauxnix поставляет MCP-сервер stdio, который предоставляет инструмент bash (плюс fauxnix_translate и fauxnix_session). Подключите любой MCP-совместимый харнесс:

Claude Code

claude mcp add fauxnix -- fauxnix mcp

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

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

Примечание: в неинтерактивном режиме codex exec вызовы MCP-инструментов автоматически отклоняются слоем одобрения; передайте --dangerously-bypass-approvals-and-sandbox (или запустите интерактивно и одобрите один раз).

OpenCode (opencode.json)

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

Kimi Code — в отличие от других, MCP-серверы живут в JSON-файле, а не в TOML-конфиге: ~/.kimi-code/mcp.json

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

Любой MCP-клиент — stdio-сервер: fauxnix mcp. Имя инструмента — bash (переопределяется через FAUXNIX_TOOL_NAME). Описание инструмента уже обучает модель поддерживаемому подмножеству, поэтому изменения системного промпта не требуются.

MCP-сессия сохраняет cwd, переменные окружения, export/unset и cd -/OLDPWD между вызовами инструментов — она ведёт себя как залогиненная оболочка, а не как stateless exec.

Что переводится

~105 команд, все выходные данные сверены с реальными GNU coreutils на Windows (Git Bash) во время разработки:

  • файлы: ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff

  • текстовые фильтры: grep egrep sed awk sort uniq cut tr — скрипты sed/awk разбираются на этапе трансляции (неподдерживаемые конструкции вызывают именованные ошибки, никогда не ведут себя молча неправильно)

  • текстовый ввод/вывод: echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs

  • оболочка/система: 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

  • сеть: curl wget ping netstat ss ip ifconfig nslookup dig host

  • архивы: tar gzip gunzip zcat zip unzip

Плюс синтаксис оболочки: пайпы, && / || / ;, перенаправления (> >> 2> 2>&1 < &>, /dev/null), кавычки, $VAR $(...) подстановка команд, префиксы VAR=x cmd, разворачивание ~ и нормализация путей в стиле POSIX (/tmp, /d/foo → D:\foo).

Коды возврата следуют соглашениям bash: 0 — ок, 1 — ошибка, 2 — использование/серьёзная, 127 — команда не найдена, 124 — таймаут.

Как это работает

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

  • Детерминированная трансляция, ноль вызовов LLM во время выполнения.

  • Каждая команда сопоставляется с генератором, который создаёт самодостаточный блок PowerShell, соблюдающий «контракт Fauxnix»: вывод построчно в stdout, [Console]::Error.WriteLine для stderr в стиле bash, $script:fx_exit для кодов выхода, $input для stdin.

  • Исполнитель оборачивает каждый скрипт принудительным UTF-8 ([Console]::OutputEncoding, $OutputEncoding, chcp 65001), декодирует вывод как строгий UTF-8 с запасным GBK(936) для унаследованных нативных инструментов, убирает сериализацию CLIXML и шум PowerShell из stderr и переписывает типичные ошибки PowerShell (включая сообщения локали zh-CN) в формулировки bash.

  • Скрипты выполняются через -EncodedCommand (UTF-16LE) и прозрачно переключаются на временный файл .ps1, когда превышается лимит командной строки в 32 КБ.

Известные отклонения (честный список)

fauxnix оптимизирован под команды, которые агенты реально запускают. Документированные отклонения:

  • X=1 отдельные присваивания следуют семантике export (одно окружение на сессию; различие между переменной оболочки и экспортированной переменной в bash не существует), и префикс в том же сегменте виден $VAR внутри собственных слов команды (Z=in [[ $Z == in ]] здесь истинно, в bash — ложно, где разворачивание слов предшествует временному окружению).

  • yes ограничен 65 536 строками — пайплайны PS 5.1 не могут сигнализировать вышестоящим производителям остановиться, поэтому неограниченный yes | head завис бы.

  • tail -f, eval, alias, heredoc, while/until/case, посимвольное $((...)) арифметическое разворачивание и фоновый & отклоняются с понятными сообщениями об ошибках вместо неправильного поведения. (if/then/else/fi, for x in ..., подстановка в обратных кавычках, command -v, пайплайн read и source в стиле dotenv поддерживаются.)

  • command -v <builtin> выводит /usr/bin/<name>, где bash выводит просто имя встроенной команды; коды выхода и семантика пустого результата совпадают.

  • chmod отображает только бит read-only; биты exec на Windows не работают. chown — молчаливая no-op (как в Git Bash).

  • Колонки ps aux приблизительны (нет учёта CPU% на процесс, USER показывает ?).

  • gzip -c/пайплайн stdin — текстово-точный, не байтово-точный; файловый режим gzip f — байтово-точный.

  • Пайплайн, производящий ровно одну строку, переданный в wc -l, считает эту строку (bash посчитал бы 0, если производитель опустил завершающий перенос). printf 'x' | md5sum остаётся байтово-точным.

  • sed/awk поддерживают общее подмножество; hold-space, метки, массивы, циклы вызывают именованные ошибки «не поддерживается» на этапе трансляции.

  • curl/wget отказываются от loopback/private/reserved адресов (localhost, 127.x, ::1, 10.x, 172.16–31.x, 192.168.x, 169.254.x) как безопасное значение по умолчанию для HTTP, управляемого агентом.

  • Нативные пайплайны инструментов против кодировки: PS 5.1 имеет один консольный переключатель кодировки, поэтому пайпинг локализованных админ-инструментов (ipconfig, tasklist — GBK на zh-CN) и UTF-8-нативных dev-инструментов (node, curl) не может чисто декодировать оба в середине пайплайна. По умолчанию предпочтение отдаётся UTF-8 dev-инструментам; установите FAUXNIX_NATIVE_ENCODING=ansi, когда ваши агенты ищут китайский вывод нативных Windows-админ-инструментов. Чтение файлов всегда определяется по каждому файлу (строгий UTF-8 → запасной GBK), поэтому grep/sed/awk по GBK-файлам работает в любом режиме — в отличие от Git Bash, который соответствует только кодировке, предполагаемой его локалью.

Разработка

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

Карта архитектуры: src/parser.ts (подмножество bash → AST) · src/translator.ts (AST → PowerShell + обёртка исполнителя) · src/executor.ts (запуск, перенаправления, сохранение сессии) · src/commands/*.ts (генераторы команд) · src/mcp.ts (MCP-сервер) · src/cli.ts.

Лицензия

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