클로드 스쿼드(Claude Squad) 초간단 가이드

한 줄 요약: 클로드 스쿼드는 여러 개의 Claude Code 세션을 Git Worktree 기반으로 격리시켜, 충돌 없이 병렬로 작업할 수 있게 해주는 무료 터미널 TUI 도구입니다.

GitHub - smtg-ai/claude-squad: Manage multiple AI terminal agents like Claude Code, Aider, Codex, OpenCode, and Amp.

---

1. 클로드 스쿼드가 뭔가요?

보통 Claude Code로 작업하면 한 번에 하나의 작업만 할 수 있다.

이전에 깃 워크트리를 사용하는 방법을 알아봤으나... 귀찮은 과정이 여전하다.

2026.03.08 - [Dev./AI 인공지능] - Claude Code와 Git Worktree: 혼자서 개발 팀처럼 코딩하는 법

 

기능 A를 만들고 있는데 기능 B도 동시에 시키고 싶다면? 클로드 스쿼드를 쓰면 된다!!

 

클로드 스쿼드는 내부적으로 tmux(터미널 분할)와 Git Worktree(코드베이스 격리)를 활용한다.

각 세션마다 별도의 브랜치와 작업 폴더가 자동으로 만들어지기 때문에,

여러 Claude Code 에이전트가 서로 간섭 없이 동시에 코드를 수정할 수 있다.

---

2. 설치 (2분이면 끝)

Mac 준비물

# tmux 설치 (필수)
brew install tmux        # macOS
sudo apt install tmux    # Ubuntu/Debian

# GitHub CLI 설치 (필수 - PR 푸시 등에 사용)
brew install gh          # macOS

 

방법 A — Homebrew (추천)

brew install claude-squad
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

 

방법 B — 스크립트 설치

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

설치가 끝나면 cs라는 명령어로 실행할 수 있습니다.

---

 

Window 준비물

 

윈도우에서도 할 수 있다.

다만 네이티브로 바로 되는 건 아니고, **WSL(Windows Subsystem for Linux)**을 통해서 사용해야 한다.

tmux가 리눅스/맥 전용 도구이기 때문이다.

 

1단계: WSL 설치

PowerShell을 관리자 권한으로 열고 실행.

wsl --install

재부팅 후 Ubuntu가 자동으로 설치된다.

BIOS에서 가상화(Virtualization)가 꺼져 있으면 설치되지 않는다. BIOS 설정을 변경해야 한다.

AMD CPU 가상화 활성화하기

---

2단계: WSL(Ubuntu) 안에서 필수 도구 설치

# tmux 설치
sudo apt update && sudo apt install -y tmux

# GitHub CLI 설치
sudo apt install -y gh

# Node.js 설치 (Claude Code용)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Claude Code 설치
npm install -g @anthropic-ai/claude-code

도구	체크
WSL2 Ubuntu	✔️
tmux	✔️
Node.js 24	✔️
GitHub CLI	✔️
Claude Code	✔️
Claude Squad	✔️

---

3단계: 클로드 스쿼드 설치

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

---

4단계: 실행

cs

 

참고로 GitHub Discussions에서...

윈도우 사용자들이 PowerShell, CMD, Windows Terminal 등에서 직접 실행하려다 버그를 겪는 사례가 보고되고 있다.

 

가장 안정적인 방법은 WSL Ubuntu 터미널 안에서 모든 것을 실행하는 것!

Windows Terminal 앱에서 Ubuntu 탭을 열어서 쓰면 가장 깔끔하다.

tab으로 넘길 수 있다 / 생성된 워크트리

- 오른쪽은 깃 워크트리를 생성하는 공간

- 왼쪽은 작업을 모니터링 할 수 있는 공간

윈도우에서 돌리면... 워크트리가 느리게 생성된다...
원인1) WSL → Windows 드라이브 (/mnt/d/) I/O가 느림 — WSL이 NTFS를 마운트해서 쓰는 구조라 파일 작업이 기본적으로 느리다.
원인2)  Unreal 프로젝트 파일 수가 많음 — worktree 생성 시 수천 개 파일을 체크아웃

첫 생성이라 특히 오래 걸리고, 이후엔 좀 빨라진다고 한다.

근본적으로 빠르게 하려면 Claude Squad 워크트리를 WSL 내부 (/home/cha/) 에 두는 방법이 있는데, Unreal 프로젝트 특성상 Windows 쪽에 있어야 하므로 현실적으로 어렵다.

---

3. 기본 사용법

실행

cs

이것만 치면 TUI(터미널 UI)가 뜬다. 기본 프로그램은 claude(Claude Code).

---

다른 AI 도구와 함께 쓰기

cs -p "codex"          # OpenAI Codex
cs -p "aider ..."      # Aider
cs -p "gemini"         # Gemini CLI

---

자동 승인 모드 (Yolo 모드)

cs -y

Claude가 묻는 모든 확인을 자동 수락한다. 빠르게 돌릴 때 유용!!

---

 

4. 핵심 단축키 정리

키	기능
n	새 세션 생성
N	프롬프트를 입력하며 새 세션 생성
D	선택한 세션 삭제
j / k	세션 목록 위/아래 이동
Enter 또는 o	선택한 세션에 접속 (프롬프트 입력 가능)
Ctrl+Q	세션에서 빠져나오기 (세션은 계속 실행)
Tab	미리보기 / Diff 탭 전환
s	커밋 & GitHub에 브랜치 푸시
c	체크아웃 (변경사항 커밋 후 세션 일시정지)
r	일시정지된 세션 재개
?	도움말 보기
q	종료

대문자 D : 워크트리 정리

Claude Squad 실행 가이드

1. Windows Terminal에서 Ubuntu 탭 열기
2. 프로젝트 폴더로 이동 : cd "/mnt/d/Unreal Projects/GAS"
3. 실행 : cs
* 프로젝트를 계속 이동해주는 게 번거로우니, 클로드에게 커맨드를 만들어달라고 요청!
나의 경우 'source ~/.bashrc' 후 'cs_gas'치면 바로 실행

.bashrc는 Ubuntu 터미널을 열 때 자동으로 실행되는 설정 파일.
source ~/.bashrc는 "지금 이 터미널에서 설정 파일을 다시 불러와라" 는 뜻.
즉, 터미널을 새로 열면 자동 적용되지만, 지금 열려있는 터미널에서 바로 쓰고 싶으면 한 번 실행해줘야 한다.
귀찮으면 그냥 Ubuntu 탭 닫고 새로 열어도 된다.

---

5. 실전 워크플로우 예시

3가지 작업을 동시에 진행한다고 가정:

Step 1) cs 실행

 

Step 2) N을 눌러 첫 번째 세션 생성 → 프롬프트 입력

로그인 페이지 UI를 만들어줘

 

Step 3) Ctrl+Q로 빠져나온 뒤, 다시 N을 눌러 두 번째 세션 생성

회원가입 API를 만들어줘

 

Step 4) 같은 방식으로 세 번째 세션도 생성

README.md를 업데이트해줘

 

Step 5) j/k로 세션 사이를 오가며 진행 상황을 확인한다. Tab을 누르면 코드 변경사항(diff)도 바로 볼 수 있다.

 

Step 6) 작업이 완료된 세션에서 s를 누르면 자동으로 커밋 & 브랜치 푸시가 된다.

각 세션은 독립된 Git Worktree에서 돌아가므로, 세 작업이 서로의 코드를 건드리지 않는다.

---

6. 작동 원리 (한눈에 보기)

---

7. 자주 묻는 질문

Q. 세션 생성 시 에러가 나요.
→ Claude Code를 최신 버전으로 업데이트하세요. (claude update 또는 npm update -g @anthropic-ai/claude-code)

 

Q. 무료인가요?
→ 클로드 스쿼드 자체는 완전 무료(오픈소스, AGPL-3.0)입니다. 다만 Claude Code 사용에 따른 API 비용은 별도입니다.'

 

Q. 설정 파일은 어디 있나요?
→ cs debug 명령어를 치면 설정 파일 경로를 확인할 수 있습니다.

 

Q. 모든 세션을 초기화하고 싶어요.
→ cs reset 명령어를 사용하세요.

---