macOS 전용 AI 에이전트 도구를 Windows로 포팅하며 배운 점들

저는 한동안 멀티 에이전트 코딩 워크플로우(multi-agent coding workflows)를 실험해 왔습니다. Claude Code, Codex, 그리고 Cursor를 병렬로 실행하며, 각 에이전트가 자신만의 격리된 브랜치에서 작업하도록 하는 방식입니다. 일단 제대로 작동시키고 나면, 이는 진정으로 차별화된 개발 방식이 됩니다.

이 과정을 오케스트레이션(orchestrating)하기 위해 제가 찾은 최고의 도구는 Superset by superset-sh였습니다. 이 도구는 격리된 git 워크트리(worktrees)를 통해 여러 개의 CLI 기반 코딩 에이전트를 실행하고, 단일 인터페이스에서 작업을 지시하며, 완료 시 결과를 병합할 수 있게 해줍니다. 깔끔하고, 빠르며, 잘 만들어져 있습니다.

한 가지 문제: macOS 전용입니다.

저는 Windows를 사용합니다. 그래서 약간 고집 있는 개발자라면 누구나 할 법한 일을 했습니다. 바로 포팅(port)하는 것이었죠.

Superset이 실제로 하는 일

포팅에 대해 본격적으로 다루기 전에, 왜 이 작업이 가치가 있다고 생각했는지 설명할 필요가 있습니다.

핵심 아이디어는 git 워크트리(git worktrees)를 통한 병렬 에이전트 실행입니다.

기존 방식:

사용자 → 에이전트 하나 → 브랜치 하나 → 대기 → 검토 → 반복

Superset 방식:

사용자 → 에이전트 A (feature-1 워크트리)
    → 에이전트 B (feature-2 워크트리)  
    → 에이전트 C (bugfix 워크트리)
...

각 에이전트는 자신만의 작업 디렉토리와 브랜치를 가지며, 공유 상태(shared state)가 없습니다. 준비가 되면 검토하고 병합하면 됩니다. 적절한 종류의 작업에 있어서 이는 생산성의 엄청난 변화를 가져옵니다.

Windows 포팅이 쉽지 않았던 이유

이것은 단순한 설정 변경이 아니었습니다. 몇 가지 사항에 실질적인 작업이 필요했습니다.

1. 터미널: macOS pty → Windows ConPTY

원본은 node-pty를 사용하는데, 이는 macOS/Linux에서는 잘 작동하지만 역사적으로 Windows에서는 다루기 까다로웠습니다. 저는 Windows 10 1809 버전부터 사용할 수 있는 현대적인 Windows 의사 터미널(pseudo-terminal) API인 Windows ConPTY로 전환했습니다.

// macOS: node-pty
const pty = spawn('bash', [], { 
  name: 'xterm-color',
...

ConPTY는 이제 안정적입니다. 주요 주의 사항은 일부 ANSI 이스케이프 시퀀스(ANSI escape sequences)가 약간 다르게 동작한다는 점이었으며, 출력 렌더링을 정규화하는 데 시간이 좀 걸렸습니다.

2. 파일 경로: 도처에 깔린 백슬래시 (backslashes)

Windows는 백슬래시 (backslashes)를 사용합니다. 기존 코드베이스는 워크트리 경로 (worktree paths), git 명령 (git commands), 설정 파일 (config files), 로그 출력 (log output) 등 모든 곳에서 슬래시 (forward slashes)를 사용한다고 가정하고 있었습니다.

해결 방법이 어렵지는 않았지만 지루한 작업이었습니다. 모든 내부 경로를 슬래시 (forward slashes)로 정규화한 다음, 실제로 Windows API를 호출할 때만 시스템 경계에서 변환하도록 했습니다.

// 입력 시 정규화
const normalize = (p: string) => p.replace(/\\/g, '/')

...

3. 셸 통합 (Shell integration): PowerShell / cmd / WSL

macOS에서는 bash 또는 zsh를 가정합니다. Windows에서는 다음을 처리해야 합니다:

PowerShell 7+ (권장)
cmd.exe (레거시 폴백 (legacy fallback))
WSL (Windows 상의 Linux 환경)

각각 환경 변수를 설정하고, 스크립트를 실행하며, 종료 코드 (exit codes)를 처리하는 방식이 다릅니다. 결국 저는 이 세 가지 모두에 대해 인터페이스를 정규화하는 셸 어댑터 (shell adapter) 레이어를 구현하게 되었습니다.

4. 빌드 파이프라인 (Build pipeline): dmg → nsis/msi

업스트림 (upstream) 빌드 대상은 macOS의 .dmg입니다. Windows를 위해 Electron-builder 설정을 다음을 대상으로 변경했습니다:

NSIS 설치 프로그램 (NSIS installer) (.exe) — 설치/제거를 지원하는 표준 Windows 설치 프로그램
MSI — 기업 환경용

// electron-builder.ts (Windows targets)
win: {
  target: [
...

5. 키보드 단축키 (Keyboard shortcuts): ⌘ → Ctrl

UI의 모든 키보드 단축키가 macOS 수정 키 (modifiers)를 사용하고 있었습니다. 전체 단축키 맵을 검토하여 다음과 같이 재매핑했습니다:

⌘ → Ctrl
⌥ → Alt
⌘⇧ → Ctrl+Shift

작은 부분이지만, Windows에서 네이티브 (native) 느낌을 주는 데 중요합니다.

업스트림에 알린 내용

저는 superset-sh 팀에 포팅 사실을 알리기 위해 이슈 (issue)를 생성했습니다 (superset-sh/superset#5011). SuperWin은 업스트림과 동일한 Elastic License 2.0을 유지하며, 업스트림 main 브랜치에 계속 리베이스 (rebased)되는 것을 목표로 합니다.

이것은 비공식 커뮤니티 포팅이며, superset-sh 팀과 제휴하거나 그들로부터 승인받은 것이 아닙니다. 만약 그들이 공식 Windows 빌드를 출시한다면 아주 좋은 일일 것입니다. 그때까지 SuperWin은 존재합니다.

현재 상태

✅ Windows 10 (1809+) 및 Windows 11에서 실행 가능
✅ PowerShell / cmd / WSL 지원
✅ Claude Code, Codex, Cursor 오케스트레이션 (orchestration) 작동
✅ 격리된 git 워크트리 (worktree) 관리
⏳ 아직 사전 빌드된 설치 프로그램 없음 — 현재는 소스에서 직접 빌드 필요
⏳ 향후 릴리스에서 설치 프로그램 제공 예정

요구 사항 (Requirements):

Windows용 Bun v1.0+
Git for Windows 2.40+
PowerShell 7+ (권장)

사용해 보기

git clone https://github.com/the7thfreedom/superwin.git
cd superwin
Copy-Item .env.example .env
...

GitHub: the7thfreedom/superwin

다시 한다면 다르게 할 점들

만약 처음부터 다시 시작한다면:

첫날부터 ConPTY로 시작하기 — node-pty를 작동시키려고 너무 오랜 시간을 허비한 뒤에야 전환했습니다.
경로 정규화 (Path normalization) 레이어를 최우선으로 구축하기 — 다른 무엇을 건드리기 전에 유틸리티 모듈로 먼저 추가하겠습니다.
WSL에서 더 일찍 테스트하기 — WSL의 경로 처리 (path handling)는 그 자체로 별도의 예외 케이스 (edge cases) 범주에 속합니다.

만약 당신이 AI 보조 코딩을 하는 Windows 개발자이고,
에이전트 오케스트레이션 (agent orchestration) 분야를
옆에서 지켜보고 있었다면 — 이것이 당신을 위한 진입로입니다.

질문, 피드백, 버그 리포트 모두 환영합니다. 당신의 현재
Windows에서의 AI 코딩 워크플로우 (workflow)는 무엇인가요?