fauxnix

Windows에서 Linux 스타일 명령을 실행하세요 — 네이티브하게, 결정적으로, VM과 WSL 없이.

fauxnix는 AI 에이전트를 위해 만들어진 bash→PowerShell 변환 계층입니다. 에이전트는 이미 알고 있는 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 "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에 있습니다:

Volcano Ark Coding Plan의 7개 모델 전반에서 PowerShell-vs-fauxnix 격차는 테스트한 모든 모델에서 유지되었습니다 — 최악의 경우(kimi-k2-thinking): PowerShell 작성 시 3.1배 느리고 오류 이벤트 24건인 반면, fauxnix를 통해서는 오류 0건이었습니다. fauxnix는 bash 도구 체인 없이도 실제 bash 한계의 ~15% 이내에 도달합니다.

Related MCP server: wmux

왜?

LLM 에이전트는 PowerShell보다 bash에서 훨씬 뛰어납니다. 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에서 관련 없는 2015년 웹소켓 라이브러리가 소유하고 있습니다); 설치된 명령어는 여전히 fauxnix입니다.

요구 사항: PowerShell 5.1+(기본 제공) 및 Node.js ≥ 18이 있는 Windows.

빠른 시작

# 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는 bash 도구를 노출하는 MCP stdio 서버를 제공합니다(추가로 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 서버는 TOML 구성이 아닌 JSON 파일에 있습니다: ~/.kimi-code/mcp.json

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

모든 MCP 클라이언트 — stdio 서버: fauxnix mcp. 도구 이름은 bash입니다(FAUXNIX_TOOL_NAME으로 재정의). 도구 설명이 이미 지원되는 하위 집합을 모델에게 알려주므로 시스템 프롬프트를 변경할 필요가 없습니다.

MCP 세션은 도구 호출 전반에 걸쳐 cwd, 환경 변수, export/unset, cd -/OLDPWD를 유지합니다 — 로그인된 셸처럼 동작하며, 상태 없는 exec가 아닙니다.

번역되는 것

개발 중에 Windows(Git Bash)의 실제 GNU coreutils와 출력을 대조한 ~105개 명령:

• 파일: 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 스크립트는 번역 시점에 파싱됩니다(지원되지 않는 구문은 이름 있는 오류를 던지며, 절대 조용히 잘못 동작하지 않습니다).

• 텍스트 I/O: 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 호출 없음.

• 각 명령은 “Fauxnix 계약”을 따르는 자체 포함 PowerShell 블록을 생성하는 생성기에 매핑됩니다: 줄 단위 문자열 stdout, bash 스타일 stderr용 [Console]::Error.WriteLine, 종료 코드용 $script:fx_exit, stdin용 $input.

• 실행기는 모든 스크립트를 UTF-8 강제 적용([Console]::OutputEncoding, $OutputEncoding, chcp 65001)으로 감싸고, 출력을 레거시 네이티브 도구용 GBK(936) 폴백이 있는 엄격한 UTF-8로 디코딩하며, stderr에서 CLIXML 직렬화와 PowerShell 잡음을 제거하고, 일반적인 PowerShell 오류(zh-CN 로케일 메시지 포함)를 bash 표현으로 다시 작성합니다.

• 스크립트는 -EncodedCommand(UTF-16LE)를 통해 실행되며, 32KB 명령줄 제한을 초과할 경우 임시 .ps1 파일로 투명하게 폴백합니다.

알려진 차이점 (솔직한 목록)

fauxnix는 에이전트가 실제로 실행하는 명령에 최적화되어 있습니다. 문서화된 차이점:

• X=1 단독 할당은 export 의미론을 따릅니다(세션 전체에 걸친 하나의 환경; bash의 셸 변수와 내보낸 변수 구분은 존재하지 않습니다). 그리고 같은 세그먼트의 접두사는 명령 자체의 단어 안의 $VAR에 보입니다(Z=in [[ $Z == in ]]은 여기서 참이지만, 단어 확장이 임시 환경보다 먼저 일어나는 bash에서는 거짓입니다).

• yes는 65,536줄로 제한됩니다. PS 5.1 파이프라인은 업스트림 생성자에게 중지를 알릴 수 없으므로, 제한이 없는 yes | head는 멈추게 됩니다.

• tail -f, source, eval, alias, 히어독, 백틱, 셸 제어 흐름(if/for/while) 및 백그라운드 &는 잘못 동작하는 대신 조치 가능한 오류 메시지와 함께 거부됩니다.

• chmod는 읽기 전용 비트만 매핑합니다. 실행 비트는 Windows에서 아무 작업도 하지 않습니다. chown은 조용히 아무 것도 하지 않습니다(Git Bash와 동일).

• ps aux 열은 근사치입니다(프로세스별 CPU% 계산 없음, USER는 ?로 표시).

• gzip -c/파이프라인 stdin은 바이트 단위가 아닌 텍스트 단위로 충실합니다. 파일 모드 gzip f는 바이트 단위로 정확합니다.

• 정확히 한 줄을 생성하는 파이프라인을 wc -l에 파이프하면 그 줄을 셉니다(bash는 생성자가 끝의 줄바꿈을 생략한 경우 0을 셉니다). printf 'x' | md5sum은 바이트 단위로 정확합니다.

• sed/awk는 공통 하위 집합을 지원합니다. 홀드 스페이스, 레이블, 배열, 루프는 번역 시점에 “지원되지 않음”이라는 이름의 오류를 던집니다.

• curl/wget은 에이전트 주도 HTTP의 안전 기본값으로 루프백/사설/예약 주소(localhost, 127.x, ::1, 10.x, 172.16–31.x, 192.168.x, 169.254.x)를 거부합니다.

• 네이티브 도구 파이프라인과 인코딩: PS 5.1에는 콘솔 인코딩 설정이 하나만 있으므로, 지역화된 관리 도구(ipconfig, tasklist — zh-CN에서 GBK)와 UTF-8 네이티브 개발 도구(node, curl)를 함께 파이프하면 중간에 둘 다 깨끗하게 디코딩할 수 없습니다. 기본값은 UTF-8 개발 도구를 우선합니다. 에이전트가 네이티브 Windows 관리 도구의 중국어 출력을 grep하는 경우 FAUXNIX_NATIVE_ENCODING=ansi를 설정하세요. 파일 읽기는 항상 파일별로 감지됩니다(UTF-8 엄격 → GBK 폴백). 따라서 GBK 파일에 대한 grep/sed/awk는 어느 모드에서든 작동합니다 — 로케일이 가정하는 인코딩만 일치시키는 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