20000419/fauxnix

fauxnix – AI 에이전트를 위한 Bash에서 PowerShell로의 브리지

무엇을 하는가

• 대규모언어모델(LLM) 에이전트가 Windows 머신에서 일반적인 Linux 스타일의 bash 명령어를 작성할 수 있도록 하는 결정론적이고 LLM을 사용하지 않는 번역 계층 제공.
• 도구는 bash의 일부(109개 명령어 + 일반적인 쉘 구문)를 분석하여 동등한 PowerShell 스크립트로 변환하고, 네이티브로 실행하며, 출력은 GNU coreutils와 정확히 동일한 형식(열 레이아웃, 오류 메시지, 종료 코드, UTF-8 처리)을 보여줌.
• npm 패키지(fauxnix-cli)로 배포되며, PowerShell 5.1+ 및 Node ≥ 18이 설치된 모든 Windows에서 작동. VM도 WSL도 추가 바이너리도 필요 없음.

AI에게 왜 중요한가

• LLM 에이전트는 주로 bash로 훈련되었지만, Windows에서는 인용부호, 인코딩, 또는 사용 불가능한 유틸리티 문제로 PowerShell에서 실패하는 경우가 많음.
• 실시간으로 Bash를 PowerShell로 번역함으로써, 에이전트는 익숙한 언어를 계속 사용하면서도 Windows에서 정확히 실행되게 하여, 코드 생성 보조 도구(Claude Code, Codex, OpenCode, Kimi Code, Qwen Code) 및 모든 MCP 호환 클라이언트의 신뢰성을 향상시킴.

주요 기능

• 단일 명령어 설치 – 주요 LLM 코드 보조 도구(fauxnix install --claude 등)용 및 사용자 정의 에이전트용 일반 fauxnix mcp 서버.
• MCP 세션 지속성 – 서버는 호출 간에 현재 디렉터리, 환경 변수, 위치 인수를 기억하여 실제 인터랙티브 쉘을 모방.
• 배치 모드 – 에이전트는 일련의 단계를 전송할 수 있으며, 이들은 원자적으로 컴파일되고 실행되며 각 단계에 대해 구조화된 결과를 반환.
• 광범위한 테스트 커버리지 – 400개 이상의 자동화된 테스트와 Git Bash에서 실제 GNU coreutils와 비교된 253개 사례의 차이 코퍼스.
• 성능 – 벤치마크 결과, 동일한 작업에 대해 원시 PowerShell보다 도구 호출 오류가 약 절반으로 감소하고 최대 2.5배의 속도 향상.
• 지원되는 명령어 세트 – 핵심 파일 유틸리티(ls, cp, rm, find), 텍스트 처리(grep, sed, awk, sort), 쉘 내장 명령(cd, export, set), 네트워킹(curl, wget, ping), 아카이브 도구(tar, zip) 포함.
• 유연한 오류 처리 – 지원되지 않는 구문(예: 백그라운드 &, heredocs, 전체 eval)은 조용히 오작동하는 대신 명확한 GNU 스타일 오류 메시지를 출력.

작동 방식

1. 파서 – 가벼운 bash 하위 집합 파서가 AST를 생성.
2. 번역기 – AST를 "Fauxnix 계약"(행별 stdout, 에러 스트림, 종료 코드)을 따르는 자가 포함형 PowerShell 스크립트로 변환.
3. 실행기 – PowerShell(-EncodedCommand 또는 임시 .ps1 파일)을 통해 실행되며 UTF-8 강제 적용 및 출력 후처리를 통해 PowerShell 고유의 노이즈 제거.
4. MCP 서버 – fauxnix mcp로 도구를 MCP 서비스로 노출하여 표준 모델-코드 프로토콜로 에이전트가 호출 가능.

설치 및 빠른 시작

# 설치 없이 단일 명령어 실행
npx fauxnix-cli@latest "ls -la src | head -3"

# 글로벌 설치 및 LLM 보조 도구에 연결
npm install -g fauxnix-cli
fauxnix install --claude   # 또는 --codex, --kimi, --qwen

설치된 fauxnix 명령어는 직접 사용하거나 MCP 서버를 통해 사용 가능.

제한 사항 및 알려진 차이점

• 변수 할당은 export와 동일하게 동작(쉘 로컬 및 내보낸 변수의 구분 없음).
• 일부 bash 기능은 의도적으로 비지원(예: yes는 제한, tail -f, 백그라운드 &).
• chmod는 읽기 전용 비트만 처리. chown은 Windows에서 무시됨.
• 일부 출력 세부사항(예: ps aux 열 값)은 근사치.

보안 리포지토리에는 SECURITY.md에 신뢰 모델, 네트워크 가드, 보고 절차가 기술되어 있음.

라이선스 MIT © 20000419.

---

Fauxnix는 AI 에이전트가 훈련된 언어인 Bash를 그대로 사용하면서도, 네이티브 Windows에서 안전하고 효율적으로 실행되도록 합니다.