English | 中文

멀티 에이전트(Multi Agents)를 사용하는 이유 · 비교 · v7 UI · 빠른 시작 · tmux 기초 · 에이전트 설정 · 설치

작은 작업에는 단일 에이전트(Single agent)로도 충분합니다. 하지만 작업에 계획, 병렬 편집, 리뷰, 테스트 및 인수인계가 필요해지면, 멀티 에이전트(Multi agents)는 역할, 컨텍스트(Context), 모델(Models), 실행(Execution)을 분리하는 데 도움을 줍니다. CCB는 여러 개의 실제 CLI 에이전트들을 하나의 가시적인 터미널 워크스페이스(Terminal workspace)에 배치하는 데 집중합니다.

• 혼합된 역할로 인한 컨텍스트(Context) 집중도 저하: 하나의 대화 안에서 아키텍처 설계, 편집, 테스트, 리뷰를 모두 시도하게 됩니다.
• 복잡한 작업 실행의 한계: 긴 작업에는 분할 지점, 인수인계(Handoffs), 점검, 롤백(Rollback) 경계가 필요합니다.
• 더 높은 비용 압박: 모든 단계에서 가장 강력한 모델이 필요하다면

CCB는 복잡한 워크플로(workflows)도 지원하지만, 자동 DAG 생성기는 아닙니다. 사용자는 .ccb/ccb.config, 윈도우(windows), 역할 메모리(role memory), 워크트리(worktrees), 모델/API 설정, 그리고 ask/callback 경로를 통해 명시적으로 복잡성을 설계합니다.

CCB는 프로젝트 레벨의 에이전트 CLI 워크스페이스(workspace)입니다. tmux를 사용하여 여러 개의 실제 CLI 에이전트를 관리하며, 하나의 프로젝트를 위한 시작, 복구, 통신, 구성, 윈도우 및 런타임 상태(runtime state)를 통합합니다.

가짜 패널이 아닌 실제 CLI 세션: 모든 에이전트 창(pane)은 실제 제공업체의 CLI를 실행합니다. 가시적인 협업: 사이드바(sidebar)에 윈도우, 에이전트, 상태 및 통신 정보가 표시되며, 사용자는 마우스로 창을 전환할 수 있습니다. 혼합된 제공업체(Mixed providers): 하나의 프로젝트에서 Codex, Claude, Gemini, OpenCode, Droid를 함께 실행할 수 있습니다. 프로젝트 구성: .ccb/ccb.config에서 팀, 레이아웃, 윈도우, 워크트리, 모델, 키 및 URL을 정의합니다. 복구 가능한 런타임: CCB는 에이전트 창을 감독하며 attach, 복구(restore) 및 프로젝트 범위의 정리(cleanup)를 지원합니다. 명시적인 협업 채널: 에이전트는 /ask, $ask, callback 및 silence 경로를 통해 작업을 위임할 수 있습니다.

이 스크린샷은 ccb_test2 프로젝트의 실제 다크 터미널 세션입니다. 레이블이 각 영역을 설명하므로 모든 단축키를 먼저 외울 필요는 없습니다.

사이드바 구현은 tmux-agent-sidebar의 아이디어를 사용했습니다. 해당 프로젝트에 감사드립니다.

신규 사용자는 릴리스 패키지(release package)부터 시작하는 것이 좋습니다. Releases에서 일치하는 패키지를 다운로드한 후 다음을 설치하세요:

tar -xzf ccb-*.tar.gz
cd ccb-*
./install.sh install

이미 CCB가 설치되어 있는 경우:

ccb update

소스 설치 (Source install)는 개발용 또는 폴백 (fallback) 용도입니다

git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
./install.sh install

소스 설치는 글로벌 ccb를 연결합니다.

/ ask

체크아웃 (checkout) 상태로 돌아갑니다. 일반 사용자는 안정적인 릴리스 (stable release) 설치 또는 업데이트를 권장합니다.

프로젝트 루트에 .ccb/ccb.config를 생성합니다. v7의 경우, 멀티 윈도우 토폴로지 (multi-window topology)로부터 설정을 먼저 이해하는 것이 좋습니다: [windows]

은 tmux 윈도우와 에이전트 그룹 (agent groups)을 정의하며, agent:provider

은 각 에이전트가 어떤 CLI를 사용할지 정의하고, (worktree)

는 에이전트에게 고유한 git 워크트리 (worktree)를 부여합니다.

version = 2
entry_window = "main"
[windows]
...

윈도우를 어떻게 그룹화할지, 얼마나 많은 워커 (workers)가 필요한지, 어떤 에이전트가 워크트리를 사용해야 하는지, 또는 어떤 에이전트가 별도의 모델이나 API 경로 (API routes)를 필요로 하는지 확실하지 않다면, ccb-config 스킬을 가진 에이전트에게 질문하여 함께 논의하고 설정 제안 (config proposal)을 생성해 보세요.

설정 검증:

ccb config validate

워크스페이스 (workspace) 시작:

ccb

에이전트 창 (agent pane)에 직접 입력하거나, 에이전트 간에 작업을 전달할 수 있습니다:

/ask reviewer review the latest parser changes and list blocking issues.

CCB는 대부분 마우스로 사용할 수 있지만, 몇 가지 tmux 단축키를 익히면 일상적인 작업 속도가 훨씬 빨라집니다. 이 섹션에서는 일반적인 tmux 키보드 조작만을 나열합니다.

이 섹션에서 <prefix>

는 Ctrl-b를 의미합니다: Ctrl-b를 누르고 뗀 다음, 기능 키 (function key)를 누르세요. 문장 부호 키가 다른 입력기 (IME)에 의해 가로채이지 않도록 기능 키를 누를 때는 영어 입력 방식을 사용하세요.

복사 및 붙여넣기 팁:

마우스 복사: 대부분의 터미널에서는 왼쪽 마우스 버튼으로 드래그하여 복사할 수 있습니다. 만약 tmux가 드래그를 가로챈다면, 먼저 복사 / 스크롤 모드에 진입하세요. tmux 선택 건너뛰기 (Bypass tmux selection): 많은 터미널이 터미널 자체 선택 기능을 위해 Shift + 마우스 드래그를 지원합니다.

시스템 붙여넣기: Linux/Windows 터미널은 보통 Ctrl+Shift+V를 사용하며, macOS 터미널은 보통 Cmd+V를 사용합니다.

tmux 붙여넣기: 내용이 tmux 버퍼에 있다면 기능 키 ]를 사용하세요.

더 일반적인 tmux 작업들

신규 사용자들은 처음에는 Pane/Window 종료 단축키 사용을 피해야 합니다. CCB 프로젝트를 중단할 때는 실수로 복구 가능한 Pane을 종료하는 대신, CCB의 프로젝트 레벨 종료 명령을 사용하는 것을 권장합니다.

CCB는 설정(Config)을 낮은 우선순위에서 높은 우선순위 순으로 세 가지 계층에서 해결합니다:

• 내장 기본 설정 (Built-in default config).
• ~/.ccb/ccb.config에 위치한 사용자 설정 (User config).
• .ccb/ccb.config에 위치한 프로젝트 설정 (Project config).

상위 계층은 하위 계층을 전체적으로 대체하며, 병합(Merge)되지 않습니다. 프로젝트 권한 파일은 .ccb/ccb.config입니다. 기존의 .ccb_config/ccb.config 경로는 레거시 마이그레이션(Legacy migration) 흔적일 뿐입니다.

.ccb/ccb.config는 주로 다음을 제어합니다:

직접 작성하기 전에 설정을 논의하고 싶다면, ccb-config 스킬을 사용하여 대상 팀을 설명하세요. 이 스킬은 먼저 완전한 설정을 제안한 다음, 확인을 거친 후에만 .ccb/ccb.config를 작성합니다.

설정 형식 예시: 단일 윈도우, 다중 윈도우, 에이전트별 모델/API

cmd; main:codex, worker1:codex(worktree); reviewer:claude

의미:

cmd는 에이전트가 아닌 셸 팬(shell pane)입니다. main, worker1, reviewer는 에이전트 이름입니다. codex와 claude는 프로바이더(provider)입니다. ;는 왼쪽에서 오른쪽으로 분할하며, ,는 위에서 아래로 쌓습니다. (worktree)는 해당 에이전트가 격리된 git worktree를 사용함을 의미합니다.

기획(planning), 구현(implementation), 리뷰(review), 조사(research)를 서로 다른 tmux 윈도우에서 수행하고 싶다면, version = 2와 [windows]를 사용하세요:

version = 2
entry_window = "main"
[windows]
...

참고: cmd는 컴팩트/하이브리드 단일 윈도우 레이아웃에 속합니다. [windows] 내부에 cmd를 넣지 마세요.

레이아웃만으로 충분할 때는 컴팩트(compact) 형식을 사용하세요. 일부 에이전트에게 별도의 모델이나 API 경로가 필요한 경우, 컴팩트 헤더를 유지하면서 TOML 오버레이(overlays)를 추가하면 됩니다:

cmd; fast:codex, deep:codex; reviewer:claude
[agents.fast]
model = "gpt-5-mini"
...

공개 저장소(public repository)에 실제 API 키를 커밋하지 마십시오. key 및 / url은 에이전트 로컬(agent-local) 단축키이며, 고급 제공자 환경 변수(provider environment variables)는 제공자 프로필(provider profile) 또는 에이전트 환경(agent env) 필드에 포함되어야 합니다.

.ccb/ccb.config 파일을 직접 작성하고 싶지 않다면, 스킬(skills)을 지원하는 에이전트에게 ccb-config를 사용하도록 요청하십시오. 프로젝트 목표, 병렬성(parallelism), 윈도우 그룹화(window grouping), 워크트리 격리(worktree isolation), 제공자/모델/API 선호도를 설명하면, 에이전트가 구성 형태에 대해 논의하고 완전한 설정(config)을 제안할 것입니다.

예시:

$ccb-config Python 라이브러리를 위한 팀을 설계해줘: 메인(main)은 작업을 조정하고, 세 명의 워커(worker)는 워크트리(worktree)에서 구현하며, 한 명의 리뷰어(reviewer)는 회귀(regression) 및 리스크를 점검한다. 이것이 단일 윈도우(single-window)로 유지되어야 하는지, 아니면 main/work/review 윈도우로 나뉘어야 하는지 추천해줘.

ccb-config 작성 흐름 및 경계

• 자연어로 프로젝트와 팀 목표를 설명합니다.
• ccb-config는 현재 설정 권한(config authority)을 읽고 이것이 새로운 설정인지, 수정인지, 또는 마이그레이션(migration)인지 결정합니다.
• 쓰기(writing)를 수행하기 전에 하나의 완전한 설정을 제안합니다.
• 사용자가 제안을 확인하면, .ccb/ccb.config 파일만 수정합니다.
• 설정을 검증하고 변경 사항을 적용하기 위해 CCB를 재시작하라고 안내합니다.

기본적으로 ccb-config는 .ccb/ccb_memory.md 또는 .ccb/agents/<agent>/memory.md를 수정하지 않습니다. 워크플로 메모리(workflow memory) 또는 역할 메모리(role memory) 설계를 명시적으로 요청할 때만 해당 메모리 파일들을 수정해야 합니다.

일반적인 ask는 제출 후 반환(submit-and-return) 방식입니다. 대상 에이전트에게 작업을 전달한 후, 현재 에이전트는 폴링(polling)하며 기다려서는 안 됩니다.

콜백(callback)이 중요한 이유

에이전트 A가 사용자로부터 시작된 CCB 작업을 처리 중이며 이를 완료하기 위해 에이전트 B의 결과가 필요한 경우, A는 콜백(callback)을 사용해야 합니다. CCB는 부모/자식 관계(parent/child relationship)를 기록하여 A의 현재 턴(turn)을 종료시키고, 나중에 B의 결과를 A에게 연속된 작업(continuation)으로 전달합니다. 이를 통해 폴링, 큐 차단(queue blocking), 컨텍스트 낭비를 방지할 수 있습니다.

CCB는 에디터를 떠날 필요가 없습니다. 일반적인 설정은 다음과 같습니다: 코딩을 위한 에디터, 그리고 멀티 에이전트 계획(multi-agent planning), 구현, 리뷰, 테스트 및 핸드오프(handoff)를 위한 CCB 터미널입니다.

• Python 3.10+
  tmux

• Codex, Claude, Gemini, OpenCode 또는 Droid와 같이 사용할 계획인 최소 하나 이상의 에이전트 CLI

• Linux, macOS 또는 WSL

현재 v7 및 최신 버전은 네이티브 Windows 지원을 주장하지 않습니다. 네이티브 Windows 지원은 v5 라인에만 적용됩니다. Windows를 사용 중이고 최신 버전을 원한다면, WSL을 사용하고 ccb와 에이전트 CLI 모두 WSL 내부에 유지하십시오.

최초 설치 시에는 GitHub Releases의 패키지를 사용하는 것을 권장합니다. 기존 설치의 경우:

ccb update