ClawTeam: 혼자 일하던 AI Agent를 “팀”으로 바꾸는 멀티 에이전트 CLI

AI Agent가 코드를 짜고, 문서를 읽고, 실험을 돌리는 시대가 왔습니다. 그런데 막상 복잡한 일을 맡겨보면 금방 한계가 드러납니다. 에이전트 하나는 똑똑할 수 있어도, 큰 작업을 병렬로 쪼개고, 서로 결과를 주고받고, 충돌 없이 합치고, 다시 우선순위를 바꾸는 일까지 잘하진 못합니다. 결국 사람 개발자가 “매니저” 역할을 하게 됩니다. (GitHub)

ClawTeam은 바로 그 지점을 겨냥한 프로젝트입니다. 저장소 설명 그대로, 이 프로젝트는 framework-agnostic한 멀티 에이전트 coordination CLI이고, 에이전트가 다른 에이전트를 spawn하고, task를 나누고, inbox로 메시지를 주고받고, git worktree로 각자 격리된 작업 공간에서 일하게 만듭니다. 즉 “에이전트 1명”이 아니라 “에이전트 팀”을 운영하는 도구입니다. 저장소는 GitHub의 HKUDS 조직에서 공개했고, 2026년 3월 18일 공개 런칭, 3월 23일 v0.2.0 릴리스를 알렸습니다. (GitHub)

ClawTeam/pyproject.toml at main · HKUDS/ClawTeam

 

---

프로젝트 소개

ClawTeam을 한 문장으로 정리하면 이렇습니다.

CLI 기반 AI 에이전트 오케스트레이션 시스템입니다.
사람은 목표만 주고, leader agent가 worker agent를 띄우고, 작업을 분배하고, 진행 상황을 모니터링하고, 결과를 수집하도록 설계되어 있습니다. README는 이를 “One Command Line: Full Automation”이라고 설명합니다. (GitHub)

이 프로젝트가 흥미로운 이유는 기존 멀티 에이전트 프레임워크와 접근이 조금 다르기 때문입니다. 많은 프레임워크가 Docker, 별도 큐, 클라우드 인프라, YAML 오케스트레이션에 기대는 반면, ClawTeam은 기본적으로 파일시스템 + tmux + git worktree 위에서 돌아갑니다. 즉, “에이전트 운영”을 새로운 런타임 위에 올리기보다, 개발자가 이미 쓰는 로컬 개발 도구 위에 얹습니다. README도 setup이 pip install과 프롬프트 수준으로 단순하고, 인프라는 파일시스템과 tmux 중심이라고 직접 비교합니다. (GitHub)

기술 스택도 명확합니다. 패키지는 Python 3.10+ 기반이며 Typer, Pydantic, Rich, Questionary, MCP를 사용하고, 선택적으로 P2P 전송을 위해 pyzmq를 붙일 수 있습니다. Web UI는 React 18과 Vite 기반입니다. (GitHub)

---

왜 ClawTeam이 등장했을까

ClawTeam의 문제의식은 README의 “Why ClawTeam?” 섹션에 꽤 선명하게 드러납니다.
오늘날 AI 에이전트는 강력하지만, 대부분 고립된 단일 실행 단위로 일합니다. 복잡한 작업이 들어오면 사람이 직접 여러 에이전트에게 역할을 나눠주고, 각자의 컨텍스트를 관리하고, 산출물을 다시 합쳐야 합니다. ClawTeam은 이 수동 조정을 없애고, 에이전트가 팀처럼 자율 조직화하도록 만들겠다는 접근입니다. (GitHub)

이 프로젝트가 특히 개발자에게 와닿는 이유는, 멀티 에이전트를 “추상적 AI 개념”이 아니라 “실제 개발 운영 문제”로 풀기 때문입니다.

예를 들어 병렬 구현을 시키고 싶다면 보통 이런 문제가 생깁니다.

• 두 에이전트가 같은 파일을 동시에 건드린다.
• 한 에이전트 결과를 다른 에이전트가 알아야 한다.
• 누가 무엇을 맡았는지 금방 엉킨다.
• 실시간 진행 상황을 사람이 일일이 추적해야 한다.

ClawTeam은 여기에 대해 각각 git worktree, inbox/message transport, task dependency, board/dashboard라는 식으로 꽤 구체적인 답을 내놓습니다. 이 점이 단순한 “에이전트 여러 개 실행기”가 아니라, 협업 시스템에 가깝게 느껴지는 이유입니다. (GitHub)

---

핵심 기능

1. 에이전트가 에이전트를 만든다

ClawTeam의 가장 중요한 컨셉은 leader agent가 clawteam spawn을 호출해 worker를 만든다는 점입니다. 각 worker는 독립된 정체성과 실행 환경을 받습니다. README는 각 worker에 대해 git worktree, tmux window, identity가 자동으로 할당된다고 설명합니다. 실제 tmux backend 코드를 보면, spawn 시 CLAWTEAM_AGENT_ID, CLAWTEAM_AGENT_NAME, CLAWTEAM_AGENT_TYPE, CLAWTEAM_TEAM_NAME 같은 환경 변수를 주입하고, 각 에이전트를 tmux 세션의 개별 윈도우에서 실행합니다. (GitHub)

이 구조의 장점은 간단합니다.
에이전트가 “내가 누구인지, 어떤 팀에 속했는지, leader가 누구인지”를 프롬프트뿐 아니라 런타임 환경에서도 명확히 인식하게 됩니다.

clawteam spawn --team my-team \
  --agent-name worker1 \
  --task "Implement auth module"

이 한 줄의 의미는 단순히 프로세스 하나를 띄운다는 수준이 아닙니다.
실제로는 “팀에 새 멤버를 추가하고, 실행 컨텍스트를 주입하고, 협업 가능한 작업 단위로 등록한다”에 가깝습니다. (GitHub)

---

2. Task를 공유하고, 의존성을 추적한다

ClawTeam은 task를 별도 저장소로 관리합니다. README에는 pending → in_progress → completed / blocked 흐름과 --blocked-by를 통한 dependency chain, task wait 같은 기능이 나옵니다. 그리고 clawteam.team.tasks는 과거 경로를 유지하는 shim이고, 실제 구현은 clawteam.store 쪽 파일 기반 task store로 위임됩니다. 즉 task 시스템도 독립 모듈로 분리되어 있습니다. (GitHub)

이게 왜 중요하냐면, 멀티 에이전트 환경에서 “작업 쪼개기”보다 더 어려운 건 “작업 순서 맞추기”이기 때문입니다.

예를 들어 이런 흐름을 만들 수 있습니다.

clawteam task create webapp "Design REST API schema" -o architect
clawteam task create webapp "Implement JWT auth" -o backend1 --blocked-by T1
clawteam task create webapp "Build database layer" -o backend2 --blocked-by T1
clawteam task create webapp "Build React frontend" -o frontend

이렇게 하면 ClawTeam은 단순 TODO 리스트가 아니라, 작업 그래프에 가까운 협업 모델이 됩니다. README의 소프트웨어 엔지니어링 예시도 바로 이런 방식으로 설명합니다. (GitHub)

---

3. 에이전트끼리 메시지를 주고받는다

ClawTeam의 MailboxManager는 팀 내 메시징의 핵심입니다. 코드를 보면 메시지는 TeamMessage라는 Pydantic 모델로 구성되고, JSON bytes로 serialize된 뒤 transport 계층에 전달됩니다. 메시지를 보낼 때는 event log도 남깁니다. receive 시에는 transport가 raw bytes를 전달하고, 상위 계층인 MailboxManager가 이를 다시 TeamMessage로 파싱합니다. 즉, 전송과 의미 해석이 분리되어 있습니다. (GitHub)

README 기준 사용감은 꽤 직관적입니다.

clawteam task list my-team --owner me
clawteam inbox send my-team leader "Auth done. All tests passing."

이 설계가 좋은 이유는 메시징을 AI 프레임워크 내부 이벤트가 아니라 명시적이고 관찰 가능한 CLI 프로토콜로 만들었기 때문입니다. 사람이 디버깅하기 쉽고, 에이전트도 prompt에 주입된 명령어만 따르면 협업할 수 있습니다. (GitHub)

---

4. Git worktree로 충돌을 줄인다

이 프로젝트의 가장 실용적인 선택은 workspace isolation입니다. README는 각 에이전트가 별도 git worktree와 branch를 받으며, branch 이름은 clawteam/{team}/{agent} 패턴이라고 설명합니다. WorkspaceManager 구현도 정확히 이 패턴으로 worktree를 만들고, registry에 메타데이터를 저장하며, checkpoint/merge/cleanup까지 제공합니다. (GitHub)

이 방식은 멀티 에이전트 코딩에서 매우 현실적입니다.
컨테이너를 쓰지 않아도 되고, 하나의 repo를 복제해서 낭비하지 않아도 되며, 각 에이전트가 독립 브랜치에서 작업하니 병렬 개발 충돌을 크게 줄일 수 있습니다.

예를 들면 다음 같은 흐름이 됩니다.

# 팀 생성
clawteam team spawn-team my-team -d "Build the auth module" -n leader

# 워커 생성
clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2 flow"
clawteam spawn --team my-team --agent-name bob --task "Write unit tests for auth"

# 나중에 병합
clawteam workspace merge my-team alice
clawteam workspace merge my-team bob

실제 코드 수준에서도 create, checkpoint, merge, cleanup가 모두 workspace manager에 들어가 있어서, ClawTeam은 “에이전트 채팅 도구”가 아니라 꽤 진지한 git 기반 협업 런타임으로 보는 게 맞습니다. (GitHub)

---

5. 보드와 Web UI로 팀 전체를 관찰한다

README는 board show, board live, board attach, board serve를 주요 모니터링 기능으로 제시합니다. 이 중 board attach는 tmux 타일 뷰로 여러 에이전트를 한 번에 보고, board serve는 Web UI를 띄웁니다. (GitHub)

흥미로운 건 Web UI 구현이 꽤 소박하면서도 실용적이라는 점입니다.
board/server.py를 보면 Python 표준 라이브러리의 http.server 기반 경량 서버이고, /api/overview, /api/team/<team>, /api/events/<team> 같은 엔드포인트를 제공하며, 실시간 업데이트는 WebSocket이 아니라 SSE로 밀어줍니다. 로컬 도구다운 선택입니다. 별도 거대한 백엔드 프레임워크를 올리지 않고도 충분히 동작합니다. 로드맵 문서에서도 Web UI와 SSE 기반 실시간 보드를 이미 완료된 항목으로 적고 있습니다. (GitHub)

---

프로젝트 아키텍처 분석

ClawTeam의 구조를 개발자 시선으로 정리하면, 크게 다섯 층입니다.

1. CLI 레이어
   Typer 기반 명령어 엔트리. clawteam 명령 전체를 묶고 config, spawn, board, team 관련 기능을 노출합니다. (GitHub)
2. Team/Coordination 레이어
   TeamManager, MailboxManager, task store가 팀 생성, 멤버 관리, 메시징, 작업 추적을 담당합니다. (GitHub)
3. Spawn 레이어
   tmux/subprocess backend, adapter, prompt builder가 실제 에이전트 프로세스를 띄우고 컨텍스트를 주입합니다. (GitHub)
4. Workspace 레이어
   git worktree 기반 격리, merge, cleanup, cross-agent context를 담당합니다. (GitHub)
5. Transport/Storage 레이어
   기본은 파일 기반이고, 선택적으로 ZeroMQ P2P transport를 붙일 수 있습니다. 메시지 transport는 추상화돼 있고, task store도 모듈화되어 있습니다. (GitHub)

아래처럼 이해하면 전체 그림이 잘 잡힙니다.

더 내부적으로 보면, ClawTeam이 잘 설계된 지점은 관심사 분리입니다.

• 메시징은 MailboxManager가 의미를 알고, Transport는 bytes만 옮깁니다.
• task는 별도 store로 분리됩니다.
• workspace는 git 작업을 전담합니다.
• spawn은 프로세스 실행과 prompt injection에 집중합니다.

이 구조 덕분에 “기능을 빨리 붙인 해커톤 프로젝트”가 아니라, 이후 transport 교체나 storage 확장이 가능한 골격을 갖춘 상태입니다. 실제 transport-architecture.md도 MailboxManager 위에 Transport 추상층을 두고, FileTransport와 P2PTransport를 갈아끼우는 구조를 문서화하고 있습니다. (GitHub)

---

메시징 구조는 왜 꽤 잘 만들었나

ClawTeam에서 가장 인상적인 부분 중 하나는 transport 설계입니다.

기본 FileTransport는 메시지를 recipient inbox 디렉터리 밑 msg-*.json 파일로 저장하고, tmp 파일 후 rename 방식으로 원자적 쓰기를 보장합니다. 메시지 소비 과정에서는 claim/ack 개념과 dead letter 격리도 보입니다. 즉, 단순히 “파일 하나 읽고 지운다” 수준이 아니라, malformed payload 처리와 잠금 경쟁까지 어느 정도 고려했습니다. (GitHub)

선택적 P2PTransport는 ZeroMQ PUSH/PULL을 쓰고, peer discovery는 공유 파일시스템의 peers/{agent}.json으로 수행하며, 피어가 없으면 FileTransport로 fallback합니다. 이건 꽤 현실적인 절충입니다. 완전한 분산 메시지 브로커를 요구하지 않으면서도, 온라인이면 빠른 실시간 전송을 쓰고, 오프라인이면 파일 기반으로 살아남습니다. (GitHub)

즉 ClawTeam의 transport는 “클라우드급 메시지 시스템”은 아니지만, 개발자 로컬/실험실/공유 스토리지 환경에서 충분히 유용한 메시지 레이어라는 방향성이 분명합니다. (GitHub)

---

프롬프트 설계도 꽤 실무적이다

spawn/prompt.py를 보면 ClawTeam은 worker에게 단순한 자연어 task만 던지지 않습니다.
에이전트 프롬프트에 Identity, Workspace, Task, Context, Coordination Protocol, Worker Loop Protocol을 함께 넣습니다. 특히 task 목록 조회, 상태 변경, leader에게 메시지 전송, idle 보고, 세션 저장, 비용 보고까지 CLI 명령 단위로 명시합니다. (GitHub)

이 설계는 중요합니다.
에이전트 협업이 잘 안 되는 가장 흔한 이유는 “협업 규칙이 암묵적”이기 때문입니다. ClawTeam은 그 규칙을 프롬프트 안에 운영 프로토콜로 적어 넣습니다. 그래서 worker 입장에서는 “코드 작성”뿐 아니라 “작업 시작/완료/대기/보고”까지 일관된 루프를 따르게 됩니다. (GitHub)

---

실제 사용 예시

1. 풀스택 기능 병렬 개발

백엔드 인증, DB 레이어, 프론트 UI를 동시에 진행해야 하는 작업에 잘 맞습니다.

clawteam team spawn-team todo-app -d "Full-stack todo app" -n leader

clawteam spawn --team todo-app --agent-name architect --task "Design REST API schema"
clawteam spawn --team todo-app --agent-name backend --task "Implement JWT auth"
clawteam spawn --team todo-app --agent-name db --task "Build database layer"
clawteam spawn --team todo-app --agent-name frontend --task "Build React frontend"

clawteam board attach todo-app

이 경우 사람은 각 에이전트 창을 보면서 개입할 수도 있고, leader에게만 큰 방향을 수정하라고 지시할 수도 있습니다. README의 agentic software engineering 예시도 거의 이런 시나리오를 보여줍니다. (GitHub)

2. 실험 자동화

README는 8개 GPU, 8개 에이전트로 2430+ 실험을 수행해 val_bpb를 1.044에서 0.977로 개선한 autoresearch 사례를 소개합니다. 이 사례에서 leader는 GPU별로 연구 방향을 나누고, 주기적으로 결과를 읽고, 더 좋은 설정을 다른 agent에 재분배합니다. (GitHub)

즉 ClawTeam은 단순히 코드 생성용만이 아니라, 실험 매니지먼트에도 잘 맞습니다.

3. 팀 템플릿 실행

ClawTeam은 TOML 기반 템플릿으로 팀 archetype을 미리 정의합니다. 내장 예시는 hedge-fund 템플릿인데, portfolio manager, value/growth/technical/fundamentals/sentiment analyst, risk manager까지 역할이 쪼개져 있습니다. clawteam launch hedge-fund 한 번으로 팀을 띄우게 되어 있습니다. (GitHub)

clawteam launch hedge-fund \
  --team fund1 \
  --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"

이 템플릿 구조는 사실 금융보다 더 일반적입니다.
문서 리뷰팀, QA 팀, 마이그레이션 팀, 논문 분석팀 같은 식으로 재사용할 수 있습니다. (GitHub)

---

개발자가 이 프로젝트를 언제 쓰면 좋을까

ClawTeam은 모든 AI 작업에 필요한 도구는 아닙니다.
단일 프롬프트로 끝나는 작업에는 오히려 과합니다.

하지만 아래 상황에는 꽤 잘 맞습니다.

작업이 병렬화 가능한데, 서로의 상태 추적도 필요한 경우

예를 들어 API, 프론트, 테스트, 문서화를 동시에 진행해야 한다면 ClawTeam의 task + inbox + board 조합이 강력합니다. (GitHub)

에이전트가 실제 Git 워크플로에 들어와야 하는 경우

단순 대화형 보조가 아니라, branch 단위로 분리된 변경을 만들고, 나중에 머지하고, 체크포인트를 남겨야 한다면 worktree 접근이 특히 유용합니다. (GitHub)

로컬 중심, 가벼운 인프라로 멀티 에이전트를 실험하고 싶은 경우

Redis나 별도 오케스트레이터 없이, Python과 tmux와 git만으로 시작할 수 있다는 점이 강점입니다. README도 설치 요구사항을 Python, tmux, CLI coding agent 정도로 설명합니다. (GitHub)

---

아쉬운 점도 있다

좋은 프로젝트지만 현재 버전이 아직 alpha 성격이라는 점은 분명합니다. pyproject.toml classifier도 Development Status 3 - Alpha로 표시되어 있습니다. (GitHub)

그리고 구조상 이런 한계도 보입니다.

첫째, 기본 스토리지는 파일시스템 중심입니다. 로컬 실험에는 가볍고 좋지만, 대규모 동시성이나 강한 내구성이 필요한 환경에는 한계가 있을 수 있습니다. 로드맵도 이후 Redis 같은 더 강한 backend 가능성을 열어두고 있습니다. (GitHub)

둘째, 에이전트 품질은 결국 외부 CLI agent 품질에 크게 의존합니다. ClawTeam은 orchestration 레이어이지, 모델 자체의 추론 능력을 해결하는 프로젝트는 아닙니다. README도 Claude Code, Codex, OpenClaw, Cursor 등 다양한 CLI agent와 호환된다고 설명합니다. 즉 ClawTeam의 강점은 “팀 운영”이지 “모델 성능 향상” 그 자체는 아닙니다. (GitHub)

셋째, 협업 규칙을 제대로 설계하지 않으면 leader prompt가 빈약한 그냥 다중 프로세스 실행기로 퇴화할 수 있습니다. 이 프로젝트를 잘 쓰려면 template, task granularity, merge 정책을 함께 설계해야 합니다. 이건 단점이라기보다, 멀티 에이전트 시스템이 원래 가지는 운영 복잡도에 가깝습니다. 이 평가는 README와 코드 구조를 기반으로 한 해석입니다. (GitHub)

---

정리

ClawTeam은 “AI 에이전트가 여러 명 동시에 일한다”는 아이디어를 꽤 실용적인 개발자 도구로 끌어내린 프로젝트입니다. 핵심은 화려한 추론 모델이 아니라, 팀 운영에 필요한 운영체제 같은 레이어를 제공한다는 데 있습니다. spawn, task, inbox, worktree, board라는 다섯 축이 서로 잘 맞물립니다. (GitHub)

개발자 관점에서 보면 이 프로젝트의 진짜 가치는 두 가지입니다.
하나는 멀티 에이전트를 “프레임워크 개념”이 아니라 실제 Git 워크플로와 CLI 도구 위에 올렸다는 점이고, 다른 하나는 메시징, 작업, 워크스페이스를 꽤 분리된 아키텍처로 설계해 앞으로 확장 가능성이 있다는 점입니다. (GitHub)

한마디로 요약하면 이렇습니다.

ClawTeam은 AI 에이전트를 더 똑똑하게 만드는 프로젝트라기보다, AI 에이전트가 함께 일하게 만드는 프로젝트다. (GitHub)