Tmux-IDE: Claude 멀티 에이전트 팀을 하나의 터미널에서 운영하는 OSS 도구

Who Should Read

Claude Code나 AI 코딩 에이전트를 활용 중인데 여러 작업을 병렬로 처리하고 싶어서 멀티 에이전트 환경을 구축해보려는 터미널 기반 개발자. 특히 tmux를 이미 쓰고 있지만 에이전트 orchestration 세팅이 번거롭다고 느끼는 분께 적합합니다.

Core Mechanics

• tmux-IDE는 YAML 파일(ide.yml) 하나로 tmux 세션 레이아웃을 선언적으로 정의하고, 각 pane에 Claude 인스턴스를 자동 실행시켜주는 도구입니다. 설정 파일을 수정하면 레이아웃이 실시간으로 업데이트됩니다.
• 에이전트 팀 모드에서는 'Lead' Claude 하나가 작업을 조율하고, 여러 'Teammate' Claude pane이 독립적으로 각자 맡은 태스크를 수행하는 구조입니다. 에이전트들은 공유 태스크 리스트를 통해 서로 작업을 할당하고 결과를 보고합니다.
• 설치는 curl 스크립트, npm 글로벌 설치, npx 즉시 실행 세 가지 방법을 지원하며, 설치 스크립트가 Claude Code skill도 자동 등록해줍니다. 이 skill 덕분에 Claude에게 '워크스페이스 세팅해줘'라고 말하면 스스로 레이아웃 구성까지 처리합니다.
• Next.js, Vite, Python, Go 등 주요 스택을 자동 감지하고 해당 dev server를 에이전트 pane과 함께 나란히 실행해줍니다. 프리셋 템플릿도 제공해서 빠르게 시작할 수 있습니다.
• ide.yml은 재현 가능한(reproducible) 설정 파일로, 다른 머신이나 다른 프로젝트에서도 동일한 레이아웃을 바로 재현할 수 있습니다. `tmux-ide init --template agent-team` 명령으로 기본 템플릿을 생성하고, `tmux-ide restart`로 레이아웃 변경사항을 즉시 반영합니다.
• 버전 1.2.0 기준으로 Claude Code의 실험적 환경 플래그(experimental env flag)를 자동 처리해주며, 팀 구성이나 작업 재배분도 자연어 프롬프트로 Lead Claude에게 지시하는 방식으로 작동합니다.
• 현재는 Claude만 공식 지원하며, Gemini나 OpenAI Codex 등 다른 모델과의 혼합 사용은 지원하지 않습니다. 커뮤니티에서 이 점이 아쉽다는 피드백이 있었습니다.

Evidence

• 멀티 에이전트 orchestration의 기술적 난제를 지적하는 댓글이 있었습니다. tmux에 초기 텍스트를 보내는 건 send-keys로 쉽게 되지만, 각 세션의 응답을 읽어오거나 작업 완료 여부를 감지하는 게 까다롭다는 경험을 공유했습니다. 메인 orchestrator가 여러 세션 상태를 체크하다 보면 정작 자신이 멈춰버리는 문제도 있어서, 주기적으로 상태를 확인하는 cron 방식을 고민 중이라고 했습니다.
• 멀티 에이전트 자체의 효용에 의문을 제기하는 시각도 있었습니다. 실제로 매일 많은 토큰을 소모하며 AI를 쓰고 있는 한 개발자는, 인간도 멀티태스킹의 생산성 이득이 환상에 불과하다는 연구가 있는데 에이전트라고 다를지 모르겠다며 Wikipedia 링크를 첨부했습니다. 오히려 하나의 에이전트에 집중하는 게 낫다는 의견이었습니다.
• 비슷한 목적의 대안 도구들이 댓글에 여럿 소개됐습니다. wingthing(tmux 스타일 세션 + 웹 터미널 원격 접근 지원, FOSS), smux(Claude로 1시간 만에 만들었다는 유사 도구), cmux.com 등이 언급됐습니다. 오픈소스 대안들이 빠르게 늘어나고 있다는 분위기였습니다.
• tmux를 이미 헤비하게 쓰는 개발자들에게는 기존 워크플로우와의 충돌이 우려됐습니다. 한 댓글에서는 '기존 tmux 레이아웃에 익숙해서 바꾸기 어렵다'고 했고, 또 다른 댓글에서는 'tmux + git worktree로 에이전트 여러 개를 직접 관리하는 게 번거롭긴 하다'며 이 도구의 필요성을 공감하기도 했습니다. VSCode에 익숙한 팀원 온보딩이 어렵다는 점도 터미널 IDE 전반의 한계로 언급됐습니다.
• 토큰 비용 문제를 현실적으로 짚는 댓글도 있었습니다. 여러 Claude를 동시에 돌리면 토큰 소모가 급격히 늘어나는데, 실제로 80%의 태스크를 더 작은 모델로 전환했더니 체감 품질 차이는 거의 없었다는 경험을 공유했습니다. Claude 외 다른 모델(Gemini, Codex)을 섞어 쓸 수 없다는 점도 아쉽다는 의견이 있었습니다.

How to Apply

• 새 프로젝트에서 병렬 작업(예: 프론트엔드 컴포넌트 개발과 백엔드 API 구현을 동시에)을 AI로 처리하고 싶다면, `npx tmux-ide`로 바로 체험해보고 `tmux-ide init --template agent-team`으로 ide.yml을 생성한 뒤 Lead Claude에게 '작업을 분리해서 팀원 pane에 할당해줘'라고 지시하면 됩니다.
• 기존에 tmux + Claude Code 조합을 수동으로 쓰고 있다면, ide.yml에 현재 사용하는 pane 구성(Claude pane, dev server pane, shell pane)을 선언해두면 `tmux-ide` 명령 하나로 동일 레이아웃을 언제든 재현할 수 있어 세팅 시간을 줄일 수 있습니다.
• 멀티 에이전트 orchestration을 직접 tmux send-keys로 구현하려다 세션 상태 감지 문제에 막혔다면, 이 도구의 GitHub 코드와 wingthing(https://github.com/ehrlich-b/wingthing), smux(https://github.com/gergomiklos/smux) 등 유사 프로젝트의 구현 방식을 참고해 back-and-forth 통신 패턴의 힌트를 얻을 수 있습니다.
• Claude만 지원한다는 현재 제약이 걸린다면, 프로젝트 GitHub에 Gemini/Codex 지원 요청 이슈를 올리거나, 현재 구조에서 command 필드를 다른 CLI 기반 AI 도구로 바꾸는 방식으로 커스터마이징을 시도해볼 수 있습니다.

Code Example

# 설치
curl -fsSL https://tmux.thijsverreck.com/install.sh | sh
# 또는
npm i -g tmux-ide
# 또는 즉시 실행
npx tmux-ide

# 프로젝트 초기화
cd ~/Developer/my-project
tmux-ide init --template agent-team
# → ide.yml 생성됨

# IDE 실행
tmux-ide

# 레이아웃 변경 후 재시작
tmux-ide restart

# ide.yml 예시
name: my-project
rows:
  - size: 70%
    panes:
      - title: Claude 1
        command: claude
      - title: Claude 2
        command: claude
  - panes:
      - title: Dev Server
      - title: Shell

Terminology

Related Resources

• tmux-IDE 공식 사이트
• wingthing - 유사한 FOSS 에이전트 터미널 도구 (웹 터미널 지원)
• smux - 유사한 tmux 기반 멀티 에이전트 도구
• cmux
• Wikipedia: Human multitasking (멀티태스킹 생산성 관련)