5dive 딥다이브
— 내 서버 한 대 위에 'AI 직원들로 굴러가는 회사'를 통째로 세우는 운영체제

5dive-ai/5dive는 "AI 에이전트들이 모인 회사를, 내가 소유한 서버 한 대에서 돌리는" 도구입니다. 이름 붙인 에이전트(claude, codex, grok…)를 각각 다른 모델·역할로 띄우고, 조직도(누가 누구에게 보고하는지)에 올린 뒤, 공유 할 일 목록(backlog)을 주면 서로 일을 주고받으며 자율적으로 일합니다. 그러다 사람만이 결정할 수 있는 순간이 오면 텔레그램으로 당신 휴대폰에 "탭 한 번으로 답하는" 버튼을 보냅니다. 놀라운 점은 거대한 서버 프레임워크가 아니라 셸 스크립트 한 덩어리(5dive CLI)가 전부라는 것 — 메시지 브로커도, 프로토콜도, 별도 오케스트레이터 서버도 없이 "공유 파일시스템 + 하나의 CLI"가 곧 버스(통신로) 역할을 합니다. 아직 별 14개의 초기 프로젝트지만, "멀티 에이전트 회사"라는 개념을 어떻게 최소한의 부품으로 실제 동작하게 만드는지 보여 주는 보기 드문 교본입니다. (저장소: 5dive-ai/5dive · Shell/TypeScript · ★14 · MIT)

1프로젝트 한줄 요약

"직원을 한 명씩 채용하듯 AI 에이전트를 띄우고, 조직도와 할 일 목록만 쥐여 주면 알아서 굴러가는 '1인 사장의 회사 운영체제'."

구체적으로 5dive의 실체는 약 88만 바이트짜리 단일 셸 스크립트 5dive입니다. 이건 사람이 직접 쓴 게 아니라, 읽기 좋게 쪼개 둔 src/*.sh 조각들을 build.sh가 하나로 이어 붙여 만든 '번들'입니다(설치 시 서버에 파일 하나만 떨어뜨리기 위함). 그 위에 텔레그램 봇을 다루는 TypeScript 코드(cos-lib.ts 등)와, 에이전트의 동작을 가로채 텔레그램과 연결하는 훅(hook) 스크립트들이 얹혀 있습니다.

이 문서가 파고드는 건 "어떻게 설치하나"가 아니라 그 안의 설계입니다 — "브로커도 없이 에이전트들이 어떻게 서로 일을 넘기나", "할 일이 없을 때 토큰을 한 톨도 안 쓰게 만드는 heartbeat의 트릭은 무엇인가", "AI가 멋대로 일을 끝내지 못하게 막는 '사람 결재' 게이트는 어떻게 강제되나". 멀티 에이전트 시스템을 최소한의 부품으로 짓는 법을 배우려는 사람에게 작지만 밀도 높은 교본입니다.

2왜 주목받는가

"무거운 멀티 에이전트 프레임워크"가 넘쳐나는 시대에, 정반대로 '브로커 없는 최소 설계'를 택한 점.

요즘 "AI 에이전트 여러 개를 협업시키는" 도구는 넘쳐납니다. 그런데 5dive가 라이브 멘션을 타고 화제가 된 이유는 대부분이 복잡하게 푸는 문제를 의도적으로 단순하게 풀었기 때문입니다. 다섯 가지로 정리하면:

① 브로커·프로토콜·오케스트레이터가 '없다'

보통 멀티 에이전트 시스템은 메시지 큐(브로커), 통신 규약(프로토콜), 중앙 조율 서버(오케스트레이터)를 깝니다. 5dive의 README는 정반대로 못 박습니다 — "브로커도, 프로토콜도, 오케스트레이터도 없다. 공유 파일시스템과 공유 CLI뿐." 에이전트가 다른 에이전트에게 일을 시킬 때 그냥 5dive agent send <상대> "..."를 호출하면 됩니다. CLI 그 자체가 통신로(버스)인 셈입니다.

② "사람을 부를 때만" 깨운다 (heartbeat)

가장 영리한 비용 설계입니다. 에이전트를 늘 돌리면 토큰(돈)이 줄줄 새지만, 5dive는 할 일 큐에 그 에이전트 몫의 '할 일'이 있을 때만 깨웁니다(§4 참고). 할 일이 없으면 토큰을 한 톨도 안 쓰고, 모델의 사용량 시계조차 시작되지 않습니다.

③ 결정은 사람이, 휴대폰으로 탭 한 번

에이전트가 "사람만이 결정할 수 있는 일"(예: "가격 정책을 출시할까요?")에 막히면, 그 작업을 당신에게 '주차(park)'해 둡니다. 그 질문은 텔레그램에 탭하면 답이 되는 버튼으로 도착하고, 당신이 하나를 누르면 막혀 있던 에이전트가 풀려 다시 일합니다.

④ 내 구독·내 토큰, 중간자 없음

에이전트의 인증 토큰은 모델 제공사(Anthropic·OpenAI 등)로 직접 갑니다 — 5dive 회사를 거치지 않습니다. 텔레메트리(사용 추적)도, 오류 보고도 없어 어떤 데이터도 서버 밖으로 나가지 않습니다. 공식 claude CLI를 내 Pro/Max 구독으로 그대로 쓰므로 Anthropic 정책상으로도 안전합니다.

⑤ 기본값이 안전 (격리 티어)

각 에이전트는 독립된 리눅스 사용자이고, 3단계 격리(admin/standard/sandboxed) 중 하나가 적용됩니다. 샌드박스로 묶으면 그 에이전트는 당신의 홈 디렉토리를 못 읽고 sudo도 못 씁니다. "AI에게 셸을 쥐여 주는" 위험을 OS 차원의 권한 분리로 막은 점이 돋보입니다.

다른 도구와의 비교

3기술 스택 전체 지도

놀랍도록 단순하다 — 거대한 런타임 대신 셸 + 리눅스 기본기 + 약간의 TypeScript.

5dive는 웹 서비스가 아니라 '서버 위에서 도는 에이전트 관리자'라, 보통의 백엔드/프론트엔드 구분 대신 ① CLI 코어(셸) ② 런타임·인프라(리눅스/systemd) ③ 채널·연동(TypeScript/훅)으로 나눠 보는 게 자연스럽습니다.

① CLI 코어 — Bash (본체)

② 런타임 · 인프라 (리눅스 기본기)

③ 채널 · 연동 — TypeScript + 훅

④ 빌드 · 배포

핵심 트릭은 "읽을 땐 쪼개고, 배포할 땐 합친다"입니다. build.sh가 src/*.sh를 정해진 순서로 cat(이어붙이기)해 단일 5dive 바이너리를 만들고, CI가 매 푸시마다 ./build.sh && git diff로 "번들과 소스가 어긋나지 않았는지(drift)"를 검사합니다. 설치는 curl -fsSL https://install.5dive.com | sudo bash 한 줄 — install.sh가 의존성(jq·tmux 등)을 깔고, 바이너리·systemd 유닛·훅·스킬을 내려받습니다.

4아키텍처 심화 분석

"공유 파일시스템 + 하나의 CLI = 버스." 중앙 서버가 없다는 게 곧 아키텍처다.

전체 구조의 핵심은 "각 에이전트는 독립된 리눅스 사용자 + 항상 켜진 AI CLI이고, 그들을 잇는 끈은 ① 같은 서버의 공유 파일(특히 sqlite 작업 큐)과 ② 같은 5dive CLI 호출뿐"입니다. 그림으로 보면:

한 작업의 일생 — end-to-end 흐름 따라가기

"새 작업이 큐에 들어옴 → 에이전트에 배정 → 작업 → 막히면 사람 호출 → 사람이 답 → 재개"를 파일·컴포넌트 단위로 추적해 봅시다.

5dive task add "어젯밤 CI 실패 분류" --assignee=ops --recurring="0 7 * * *"

5dive agent send coder "DIVE-42의 로그 파서 수정해줘"  # 비동기: 던지고 끝
5dive agent ask  coder "수정 다 됐어?" --timeout=120        # 동기: 답이 올 때까지 대기

5dive task need DIVE-42 --type=approval \
      --ask="가격 정책 v2를 출시할까요?" --options="ship|hold" --recommend=ship

핵심 설계 패턴 5가지

① "CLI가 곧 버스" (브로커 없는 메시지 전달)

에이전트 간 통신을 위해 메시지 큐를 깔지 않습니다. 대신 같은 5dive CLI를 호출하면, 그 명령이 상대 에이전트의 tmux 세션에 send-keys로 글자를 넣어 줍니다. "통신로를 새로 만들지 말고, 이미 있는 것(공유 파일 + 공유 실행파일)을 통신로로 쓰자"는 발상입니다.

② "할 일 있을 때만 깨우는" 비용 게이트 (heartbeat)

늘 켜 두면 비싸고, 완전히 꺼 두면 일을 못 합니다. 5dive는 그 사이를 "큐에 내 작업이 있을 때만 깨어난다"로 해결합니다. 깨우는 주기(everyMin)는 '실제로 깨어난 사이의 최소 간격'이라, cron이 더 자주 돌아도 일 없는 에이전트는 값싼 sqlite 카운트만 한 번 더 할 뿐 비용이 안 듭니다.

③ 단일 번들 + 드리프트 검사 (빌드 규율)

읽기 좋은 src/*.sh와 배포용 단일 5dive가 어긋나면 사고가 납니다. 그래서 build.sh로 항상 다시 빌드하고, CI가 git diff로 "소스만 고치고 번들을 안 고쳤거나 그 반대"인 경우를 잡아냅니다. 순서도 엄격합니다 — header.sh(전역 변수)는 맨 앞, main.sh(종료 트랩 + main "$@")는 맨 뒤.

④ OS 수준 격리 (전략 패턴 같은 보안)

에이전트마다 다른 리눅스 사용자를 만들고 systemd 유닛에 권한·자원 제한을 건 뒤, admin/standard/sandboxed 중 한 티어를 적용합니다. "샌드박스 에이전트는 홈 못 읽고 sudo 못 함" 같은 보장이 애플리케이션 코드가 아니라 OS에서 강제됩니다 — 훨씬 깨기 어려운 방어선입니다.

⑤ 사람-결재 게이트의 '진짜 사람' 증명 (gate-proof)

AI가 자기 결재를 스스로 통과시키면 의미가 없습니다. 그래서 approval·secret 게이트는 에이전트 계정(agent-*)으로는 막혀 있고(DIVE-519), 켜 두면 루트만 발급할 수 있는 '사람 출처 증명 토큰'(5dive gate-proof)이 있어야 통과됩니다. "결정의 최종 권한은 사람"을 코드로 못 박은 영리한 설계입니다.

5디렉토리 구조 해부

진짜 로직은 전부 src/ 아래 셸 조각들. 루트의 5dive는 그것들을 이어붙인 '완성품'일 뿐.

읽는 순서를 추천하자면: ① README.md(전체 개념) → ② src/main.sh(어떤 명령들이 있고 어떻게 분배되는지 한눈에) → ③ src/cmd_heartbeat.sh 상단 주석(비용 설계의 핵심) → ④ systemd/5dive-agent@.service + 5dive-agent-start(에이전트가 실제로 어떻게 뜨는지) → ⑤ src/cmd_task.sh(작업·사람결재 흐름) 순입니다. 루트의 거대한 5dive 파일은 자동 생성물이니 직접 읽지 말고 src/를 보세요.

6학습 포인트 (기술별)

이 저장소의 진짜 가치는 "멀티 에이전트 + 견고한 셸 시스템 프로그래밍"을 한곳에서 코드로 볼 수 있다는 것.

① 견고한 Bash 시스템 프로그래밍 — src/main.sh · lib/

"셸 스크립트는 대충 짜는 것"이라는 편견을 깨는 코드입니다. set -euo pipefail(오류·미정의 변수·파이프 실패에 즉시 중단), 종료 트랩으로 모든 경로가 감사 로그를 남기게 하기, 레지스터 락(with_registry_lock)으로 대시보드 동시 클릭의 경쟁 상태(race) 막기, 종료코드 표(0=ok, 4=not_found, 6=auth_required…)를 --json 에러와 일치시키기 — "셸로도 신뢰성 있는 도구를 만들 수 있다"는 모범을 보여 줍니다.

② "있는 것을 통신로로" — 에이전트 간 메시지 전달

cmd_agent.sh의 send/ask가 백미입니다. 상대 에이전트의 tmux 세션에 send-keys로 글자를 주입하고, ask는 그 뒤 화면 스크롤백이 더 이상 안 자랄 때까지 폴링해 답을 긁어옵니다. "메시지 큐 없이 동기 RPC 흉내 내기"의 실전 예시입니다. 받는 쪽엔 [5dive-msg from=<보낸이>] 꼬리표가 자동으로 붙습니다.

③ 비용을 0으로 만드는 스케줄러 — cmd_heartbeat.sh

이 파일의 상단 주석만 읽어도 큰 공부가 됩니다. "틱은 자주, 깨움은 드물게"(체크는 매 틱, 비용은 실제 깨울 때만), 리퍼(폭주하는 작업 강제 회수), 굶주림 감지(넛지해도 안 시작되는 작업 surface), 고아 회수(claude 프로세스가 죽어 주인 없는 작업 되돌리기) 등 "자율 에이전트가 멈추거나 폭주할 때"를 다루는 방어 코드가 촘촘합니다.

# heartbeat tick의 핵심 분기(요지)
no todo            -> do nothing      # 안 깨움 = 토큰 0
already in_progress -> skip            # 두 번 찌르면 일이 엉킴
has todo + due      -> /clear + 넛지 1개 # "한 작업만 하고 쉬어라"

④ systemd 유닛을 제대로 쓰는 법 — 5dive-agent@.service

템플릿 유닛(@로 인스턴스화 → User=agent-%i), 여러 EnvironmentFile로 인증·채널 환경을 겹쳐 주입, Restart=on-failure로 자동 부활. 특히 ExecStop 주석은 보석입니다 — "antigravity의 agy 바이너리는 SIGTERM을 무시하고 SIGHUP에만 죽는다"는 실전 디버깅이 그대로 코드에 남아, 종료 시간을 60초에서 0.05초로 줄인 사연이 적혀 있습니다.

⑤ 텔레그램 연결과 라이프사이클 훅 — hooks/

에이전트의 동작 지점(도구 사용 전/후, 정지 시)에 끼어드는 훅 패턴을 통째로 볼 수 있습니다. 백미는 pretool-telegram-question.sh — tmux에서만 보이는 질문 UI(AskUserQuestion)를 막고, "그 UI는 텔레그램 사용자가 못 보니, 질문을 번호 매긴 일반 메시지로 보내라"고 에이전트에게 되돌려 줍니다. "AI의 출력 형식을 채널에 맞게 교정하는" 영리한 중간 계층입니다.

⑥ 선언형 회사 구성 — team-templates/*.yaml

5dive.yaml 하나로 여러 에이전트 + 역할 + 조직도 + 시작 백로그를 선언하고 5dive up으로 한 번에 띄웁니다(도커 컴포즈와 닮음). reports_to가 조직 진실의 단일 출처라, 거기서 조직도 엣지와 각 에이전트의 CLAUDE.md에 붙는 "## 보고 라인" 섹션("당신의 상사는 누구, 부하는 누구, 이렇게 연락하라")을 자동 생성합니다 — 위임이 장식이 아니라 실제로 동작하게 만드는 부분입니다.

⑦ 텔레그램 Bot API 자동화 — cos-lib.ts

유일한 큰 TypeScript 조각입니다. 텔레그램 Bot API 9.6의 "관리형 봇"으로, 고객 소유의 '비서실장 봇'이 에이전트마다 자식 봇을 자동 생성·설정(이름·설명·아바타)·토큰 회전하게 합니다. 부수효과를 최소화한 순수 함수로 짜 단위 테스트가 가능하게 한 점, "avatar 업로드는 multipart attach:// 래퍼가 필요하다" 같은 API 함정 주석이 학습 포인트입니다.

⑧ 단일 바이너리 빌드 + 드리프트 CI — build.sh

"소스는 쪼개 읽고, 배포는 한 파일로"를 어떻게 안전하게 유지하는지 보여 줍니다. cat 순서를 엄격히 지키고(전역 먼저, main 마지막), CI가 ./build.sh && git diff --exit-code 5dive로 양방향 드리프트를 잡습니다. 생성물과 소스의 동기화를 사람 기억이 아니라 자동화로 보장하는 좋은 패턴입니다.

⑨ 사람-결재 게이트의 권한 분리 — gate-proof · 격리 티어

"AI가 자기 승인을 스스로 통과시키지 못하게" 만드는 법을 보여 줍니다. approval/secret 게이트는 에이전트 UID로는 막혀 있고, 루트만 발급하는 사람-출처 증명 토큰이 있어야 통과됩니다. 격리 티어(admin/standard/sandboxed)와 함께, "신뢰 경계를 OS 권한으로 그린다"는 보안 사고법을 배울 수 있습니다.

7시스템 요구사항

서버급 하드웨어가 필요한 게 아니다 — 핵심은 "리눅스 + systemd + 루트 권한".

8직접 해볼 수 있는 실습 과제

읽기만 하면 금방 잊는다. 난이도별로 손을 움직여 보자. (모두 일회용 VM/도커에서!)

9관련 기술 심화 학습 로드맵

이 저장소를 '교과서'로 삼아 6주간 "멀티 에이전트 + 셸 시스템 설계"를 정복하는 코스.

10핵심 키워드 사전

이 문서·저장소에 나온 용어를 한 줄씩 정리. 모르면 여기로 돌아오기.

11참고 링크

원본 저장소와, 각 개념을 더 깊이 팔 때의 출발점.