이런 분들께 추천합니다
- Windows PC에서 gstack을 써보려고 설치를 시도하시는 분
- WSL, Git Bash, Bun, Playwright 같은 낯선 이름에 막혀 설치가 멈추신 분
- 기획/디자인 용도로 AI 워크플로우를 구축하고 싶은 비개발자
- 어느 방식이 본인에게 맞는지 헷갈리시는 분
이 글은...
지난 글에서 gstack을 써보기로 결정한 이유를 적었습니다. 이번 글은 실제로 Windows PC에 설치하면서 겪은 과정을 정리한 기록입니다.
공식 README는 Windows 사용자를 이렇게 안내합니다.
Windows users: gstack works on Windows 11 via Git Bash or WSL. Node.js is required in addition to Bun — Bun has a known bug with Playwright's pipe transport on Windows. The browse server automatically falls back to Node.js. Make sure both bun and node are on your PATH.
즉 Git Bash와 WSL 둘 다 공식 지원입니다. 이 글은 두 방법의 장단점을 먼저 정리하고, 각 방법별로 설치 가이드를 따로 적었습니다.
Git Bash: Linux 흉내내는 Windows 프로그램
WSL: 진짜 Linux (Ubuntu)를 Windows 안에 설치
이 글을 따라하면
- Git Bash와 WSL 중 본인에게 맞는 방법 선택 가능
- 선택한 방법으로 gstack 설치 완료
- 설치 에러 트러블 슈팅
- 설치 후 바로 쓸 수 있는 환경 구축
방법 비교 — Git Bash vs WSL
한 줄 정리
- Git Bash = 간단하고 가볍다. Windows 환경 그대로 씀.
- WSL = 본격적인 Linux 환경을 Windows 안에 만드는 것. 대신 준비가 더 필요함.
뭘 고르면 되나
| "일단 gstack 한번 써보고 싶다" | Git Bash |
| "복잡한 설치는 싫다" | Git Bash |
| "이미 WSL 설치해놨다" | WSL |
제 선택
사실 저는 처음에 PowerShell로 명령어를 쳤는데 .\ 관련 명령어가 안 먹어서, 별 생각 없이 WSL로 넘어간 케이스입니다.
다만 Windows에서 이미 개발하던 환경을 그대로 유지하면서 gstack을 얹고 싶다면, Git Bash 방식이 더 편할 수 있습니다.
공통 준비물
어느 방법을 고르든 필요한 것:
- Claude Code — gstack은 Claude Code 위에서 동작
- Git — gstack 리포지토리 클론용
- Bun v1.0+ — gstack 빌드 도구
- Node.js — Windows 필수. Bun의 Playwright 관련 버그 때문에 gstack이 Node.js로 자동 우회(폴백, fallback: 문제가 생겼을 때 대신 쓰는 예비 방법)합니다
방법 A: Git Bash로 설치하기
1. Git for Windows 설치
git-scm.com/download/win에서 설치 파일 다운로드 후 실행. Git Bash가 함께 설치됩니다.
설치 후 Git Bash를 실행해서 모든 이후 명령어를 여기서 치세요.
2. Node.js 설치
nodejs.org에서 LTS 버전 다운로드 후 설치.
Git Bash에서 확인:
node --version
3. Bun 설치
Git Bash에서:
curl -fsSL https://bun.sh/install | bash
설치 후 Git Bash 재시작하고 확인:
bun --version
4. Claude Code 설치
Git Bash에서:
curl -fsSL https://claude.ai/install.sh | bash
5. gstack 클론과 설치
Git Bash에서:
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup
입력합니다.
그리고 Skill namming을 결정해야합니다. 10초동안 결정하지 않으면 추천방식인 1번으로 진행됩니다.
6. 첫 실행
mkdir -p ~/projects/first-try
cd ~/projects/first-try
claude
저는 예시로 홈 디렉토리 하위에 프로젝트 폴더를 만들어서 진행했지만, 기존에 작업하시는 폴더가 있다면 그곳에서 작업하셔도 무방합니다.
클로드를 처음 시작하신다면 로그인이 필요한데, OAuth URL이 뜨면 복사해서 Windows 브라우저에 붙여넣고 로그인. Git Bash로 돌아오면 인증 완료입니다.
저 같은 경우는 claude를 구독 중이니 해당 옵션(1번)을 선택했습니다.
/ 입력하면 gstack 슬래시 커맨드가 뜹니다. 설치 끝.
참고로 claude 실행과정부터는 git bash가 아닌 cmd나 powershell과 같은 다른 터미널에서도 가능합니다.
방법 B: WSL로 설치하기
1. WSL 설치
PowerShell을 관리자 권한으로 열고:
wsl --install
재부팅 후 Ubuntu가 자동 설치됩니다. 이후 명령어는 전부 WSL(Ubuntu) 안에서 실행.
이미 wsl로 우분투가 설치된 경우고 설치된 우분투 환경이 아닌 다른 우분투 환경에서 시작하고 싶으시다면 새 인스턴스를 만들어서 진행해야 합니다.
2. 기본 의존성 설치
sudo apt update
sudo apt install -y unzip curl git
unzip이 없으면 다음 단계(Bun 설치)에서 막힙니다.
3. Node.js 설치 (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version
4. Bun 설치
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bun --version
5. Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version
6. Playwright 시스템 의존성 설치 (WSL 전용 필수)
WSL은 기본적으로 브라우저용 시스템 라이브러리가 없어서 이 단계가 필요합니다.
npx playwright install-deps chromium
sudo 비밀번호 입력하면 libnss3, libatk, libdrm 등이 자동 설치됩니다.
아래 오류를 방지합니다.
(gstack setup failed: Playwright Chromium could not be launched)
7. gstack 클론과 설치
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup
8. 첫 실행
mkdir -p ~/projects/first-try
cd ~/projects/first-try
claude
OAuth URL을 복사해서 Windows 브라우저에서 로그인. WSL 터미널로 돌아와 완료.
WSL 선택 시 추가 고려사항
WSL이 사라질 가능성
저절로 사라지진 않지만 사용자 실수로는 가능합니다:
- wsl --unregister Ubuntu — 확인 프롬프트 없이 즉시 삭제
- Microsoft Store에서 Ubuntu 제거
- Windows 재설치
대비책:
- Git 원격 저장소 — 프로젝트 무조건 GitHub 등에 push
- 월 1회 WSL 전체 백업 — ex) wsl --export Ubuntu D:\backup\ubuntu.tar
- 중요 설정 파일은 별도 백업
자주 만나는 에러 5가지 (트러블슈팅)
에러 1: Error: unzip is required to install bun
환경: 주로 WSL에서 발생: Ubuntu에 unzip 기본 설치 안 됨 해결:
sudo apt install -y unzip
에러 2: Error: bun is required but not installed
환경: Git Bash, WSL 둘 다 원인가능: gstack setup이 Bun을 전제로 함 해결:
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
에러 3: gstack setup failed: Playwright Chromium could not be launched
환경: 주로 WSL 원인: Chromium 바이너리는 받았지만 시스템 라이브러리(libnss3, libatk 등) 없음 해결:
npx playwright install-deps chromium
에러 4: Native installation exists but ~/.local/bin is not in your PATH
환경: WSL 원인: Claude Code가 ~/.local/bin에 설치됐는데 셸이 해당 경로 모름 해결:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
최종 환경 구성 비교
Git Bash 선택 시
Windows 11
├── C:\Users\<user>\.claude\skills\gstack\ ← gstack 설치됨
├── C:\Users\<user>\projects\ ← 작업 폴더
└── C:\Program Files\Git\bin\bash.exe ← Git Bash
WSL 선택 시
Windows 11
└── WSL2 (Ubuntu)
├── ~/.claude/skills/gstack/ ← gstack 설치됨
├── ~/.local/bin/claude ← Claude Code
├── ~/.bun/bin/ ← Bun
└── ~/projects/ ← 작업 폴더
Windows 쪽
├── VS Code (+ WSL 확장)
└── 탐색기: \\wsl$\Ubuntu\home\<user>\projects
마무리
Git Bash와 WSL 둘 다 gstack을 정상적으로 돌립니다. 공식이 둘 다 동등하게 지원하고, Windows에서 발생하는 Bun 관련 버그도 gstack이 Node.js로 자동 우회해서 해결되어 있습니다.
저는 WSL로 갔지만, 다시 선택한다면 gstack만 쓸 거였다면 Git Bash도 충분한 선택이었을 것 같습니다. 본인 상황에 맞게 고르시면 됩니다.
설치 중에 이 글에 없는 에러를 만나셨다면 댓글로 남겨주세요. 해결 방법을 같이 찾아보거나 이 글에 추가하겠습니다.
👉 이전 편: [gstack #1] 혼자 쓰는 AI 팀: CEO, 디자이너, QA까지 갖춘 Claude Code 스킬팩
참고 링크
'IT > 스크랩(제품,도구)' 카테고리의 다른 글
| [gstack] 혼자 쓰는 AI 팀: CEO, 디자이너, QA까지 갖춘 Claude Code 스킬팩 (1) | 2026.04.19 |
|---|---|
| 브라우저에서 회로 만들고 시뮬레이션까지 — Diode (0) | 2026.02.25 |