b3os (b3rys team os)

Name: b3rys-team-os
Author: b3rys

여러 AI를 한 팀으로.
An AI team operating system for human-led multi-agent work.

🌐 한국어 · English README

b3os는 agent execution loop 에 organization responsibility loop 를 결합한 AI team operating system 입니다.

줄여서 b3os. 여러 AI 에이전트를 한 팀처럼 굴립니다. 팀원을 만들고, 텔레그램·슬랙에서 말 걸듯 일을 맡기고, 누가 뭘 맡았는지 대시보드 하나로 봅니다.

핵심은 에이전트 수가 아닙니다. AI 팀원이 한 팀으로 일하게 하는 환경이 핵심입니다.

지시  →  담당자 배정  →  작업 카드  →  실행  →  검증  →  보고  →  종료

⚠️ 본인 전용 장비에만 설치하세요. 대시보드·API는 로컬(127.0.0.1) 전용이고 앱 레벨 인증이 없습니다. 공용·공개 서버에 열려면 Cloudflare Access 같은 엣지 인증을 반드시 앞단에 두세요. → 대시보드를 도메인으로 열기

📋 시작 전 준비물

	무엇이	비고
💻	macOS	지금은 맥(실리콘)만 지원합니다. `bun`·`tmux`는 설치 스크립트가 알아서 깔아줍니다.
🤖	Claude Code 구독 (Pro 또는 Max)	AI 팀원의 두뇌입니다. claude.com/claude-code
💬	텔레그램 계정	팀원과 대화하는 통로입니다. 팀원 1명당 봇 토큰 1개를 @BotFather에서 무료로 발급합니다.

💸 비용은 Claude 구독 하나입니다 — b3os는 오픈소스(Apache 2.0)이고 별도 결제가 없습니다.
팀원 전원이 그 구독 하나를 함께 씁니다. 5명을 만들어도 사용 한도가 5배가 되지 않고,
처음에는 2~3명으로 시작해보세요.
슬랙은 선택입니다.

🚀 짧게 보면

b3os 설치
첫 AI 팀원 만들기
텔레그램·슬랙 채널 연결
팀원에게 첫 지시 보내기

그다음은 b3os가 이 흐름을 보이게 관리합니다.

🧑‍💻 클로드 코드를 설치 동반자로 세팅하세요!! (권장 경로)

b3os는 설치·영입·op(운영 봇)·단톡방 세팅까지 Claude Code 에서 진행하세요.

Claude Code부터 설치 — 없으면 먼저 Claude Code를 깔고 로그인합니다. (아무것도 없는 새 맥이라면 여기서 시작 — install.sh가 bun·tmux는 없으면 자동으로 깔아줍니다.)
b3os 설치·기동 — Claude Code 채팅에 한 줄: "이 저장소의 b3os 스킬을 설치하고 실행해줘: github.com/b3rys/b3rys-team-os" → clone → 설치 → 대시보드 → 첫 팀원 영입까지 대화로 진행합니다.
첫 팀원 영입 후에는 그 팀원에게 시키세요 — op·단톡방 세팅·라우터 켜기를 대시보드에서 헤매지 말고, Claude Code에서 "팀방 세팅하고 라우터 켜줘", "운영 봇 붙여줘" 처럼 첫 팀원에게 말하면 됩니다.
막히면 → 첫 팀원 + Claude Code로 해결 — 설치·영입·채널 연결에서 문제가 생기면 대시보드를 붙잡지 말고 첫 입사 팀원에게 Claude Code로 물어보세요. 그 팀원이 로그·설정을 직접 읽고 고칩니다. (대시보드는 상태를 보는 데 좋고, 고치는 건 Claude Code가 빠릅니다.)

🩺 잘 안 될 때 → 트러블슈팅 문서
가장 흔한 것: 봇이 아무 반응이 없다(텔레그램 플러그인이 안 붙은 경우) · 활성화가 안 끝난다 · 슬랙 멘션이 안 들어온다.

사람이 직접 해야 하는 건 텔레그램 쪽뿐: *BotFather 토큰 발급 · 봇을 그룹에 관리자로 초대(아래 "그룹방 설정" — 리액션에 필요) · 첫 팀원 페어링 승인 · 봇에 첫 DM.* 나머지는 Claude Code가 안내·처리합니다.

⚡ 가장 빠른 시작 — b3os 스킬 (권장)

여러분의 Claude Code에게 아래 한 줄을 그대로 복붙하면 됩니다.

이 저장소의 b3os 스킬을 설치하고 실행해줘: github.com/b3rys/b3rys-team-os

그러면 Claude가 skills/b3os/SKILL.md 를 ~/.claude/skills/b3os/ 에 설치하고 실행합니다. clone → 설치 → 대시보드 기동 → 첫 팀원 영입까지 자동으로 진행합니다. 사용자는 아래 "사용자가 해야 되는 것"(봇 토큰·활성화 승인)만 답하면 됩니다.

① 스킬 설치 (둘 중 택1)

A. 터미널 한 줄 (git 불필요) — 아래를 복붙:

curl -fsSL https://raw.githubusercontent.com/b3rys/b3rys-team-os/main/install-skill.sh | bash

B. 또는 Claude Code 채팅에 위 발화 한 줄을 붙여넣기.

② 실행

/reload-skills                                    # 설치 직후 1회 — 방금 설치한 스킬 로드
"이 저장소의 b3os 스킬을 설치하고 실행해줘"        # clone→설치→대시보드→첫 영입까지 대화로 안내

채팅에 붙여넣어 설치했다면 Claude가 실행까지 이어갑니다. 방금 설치한 스킬이 로드되지 않았으면 /reload-skills 한 번 후 같은 발화를 반복하세요.

스킬은 ~/.claude/skills/b3os/ 에 설치되는 개인 스킬입니다. 소스: skills/b3os · 설치 스크립트: install-skill.sh

스킬 없이 직접 설치하고 싶으면 아래 빠른 시작이 그대로 대안입니다.

사용자가 해야 되는 것 (AI가 "이건 직접 해주세요"라고 안내합니다)

b3os 스킬이 clone·설치·대시보드 기동·영입까지 자동으로 진행합니다. 다만 사용자가 직접 해야 하는 3가지는 사람이 답해야 합니다. 각 지점에서 AI(Claude Code)가 "이건 직접 해주세요"라고 안내합니다.

텔레그램 봇 토큰 발급 — @BotFather에서 /newbot 후 봇 이름·username을 정하면 토큰이 나옵니다. 이 토큰을 대시보드 영입 화면(또는 AI가 물을 때)에 붙여넣습니다. (상세: 아래 채널 연결 › Telegram)
런타임 선택 — 팀원마다 실행 환경을 고릅니다: Claude(주력·권장) · OpenClaw · Hermes. 준비물은 아래 팀원 만들기 › 영입 전 준비에 있습니다.
활성화 승인 — 본인 장비에서 팀원을 실제로 기동할지 install.sh 프롬프트에 y로 승인합니다(APPROVAL_EXECUTION_ENABLED=1). 본인 전용 맥에서만 y.

이 3가지만 답하면 영입 → 활성화 → 텔레그램 첫 대화까지 이어집니다.

🧰 빠른 시작 (스킬 없이 직접 설치)

본인 전용 맥에서 직접 설치하려면:

git clone https://github.com/b3rys/b3rys-team-os.git
cd b3rys-team-os
bash install.sh      # bun·의존성·빌드·.env 준비 + "이 장비에서 팀원 활성화 허용?" 질문
bun run start        # → 브라우저에서 http://localhost:7878/team

macOS 권장 — 팀원 활성화가 launchd 기반이라 지금은 macOS 전용, Linux는 대시보드만 됩니다. install.sh가 bun을 새로 깔았다면 새 터미널을 열거나 source ~/.zshrc(bash면 ~/.bashrc) 후 bun run start.

대시보드가 뜨면 Settings에서 팀원을 만들고 채널을 연결합니다(아래). 텔레그램 봇 토큰(@BotFather)과 활성화 승인(install.sh 프롬프트에 y)만 사람이 직접 합니다. 기본 대시보드는 채널 연결 전에도 동작합니다.

기본 운영 잡은 설치 후 조건부 옵션이 아니라 기본 ON으로 준비됩니다(대상 팀원/설정이 없으면 안전하게 no-op):

매일 과제 리뷰 핑 (06:00) — active Tasks를 점검하고 다음 액션 누락을 잡습니다.
매일 과제 리뷰 다이제스트 (06:20) — 그 결과를 모아 한 번에 보고합니다.
주간 공유 큐레이션 — 팀 학습 로그에서 정리 후보를 모읍니다.
주간 self-learning — SHARED/TEAM-OS/스킬 개선 후보를 모아 리뷰합니다.

미완 과제 재확인(continuation guard)·봇 자가치유(auto-heal)는 opt-in 입니다 — 기본으로 켜지지 않습니다.

👥 팀원 만들기

🤖 여기서부터는 두 가지 방법이 다 됩니다 — 대시보드에서 클릭하거나, Claude Code에게 말로 시키거나.
아래는 대시보드 기준 설명입니다. Claude Code를 쓰면 "팀원 만들어줘" · "슬랙 붙여줘" · "팀방 세팅하고 라우터 켜줘" · "b3os 언인스톨해줘" 처럼 말하면 됩니다.
사람이 직접 해야 하는 건 텔레그램 쪽 네 가지뿐: BotFather 토큰 발급 · 봇을 그룹에 초대 · 첫 팀원 페어링 승인 · 봇에 첫 DM.

ⓘ 먼저 Settings에서 팀 이름 · 팀장 ID · 팀장 이름을 저장하세요. 이 셋을 마쳐야 영입이 열립니다.

처음에는 빈 팀에서 시작합니다. Settings에서 첫 팀원을 추가합니다.

팀원은 세 가지를 가집니다.

이름: 사람이 부를 팀원 이름
역할: 이 팀원이 맡는 책임
런타임: 실제로 연결되는 AI 실행 환경

런타임 연결을 끝내기 전에도 팀원을 먼저 만들 수 있습니다. 팀 설계와 인프라 연결을 분리하기 위해서입니다.

⭐ 첫 영입 팀원은 자동으로 팀 coordinator 역할과 full context 능력을 부여받습니다. coordinator = 담당이 안 정해진/모호한 메시지의 기본 담당(라우팅 fallback·PM 조율), full context = 팀방(단톡방) 최근 메시지를 볼 수 있는 권한(최대 10건 / 6시간 이내)입니다. 즉 첫 팀원이 팀의 기본 리드로서 미배정 메시지를 받고 팀 대화 맥락을 봅니다. (이후 팀원은 기본적으로 이 능력이 없고, 첫 리드가 퇴사하면 다음 팀원에게 자동 승계됩니다.)

영입(활성화) 전 준비 — 런타임별 (Prerequisites)

팀원을 **실제로 기동(활성화)**하려면 런타임 준비물이 필요합니다(활성화 화면이 빠진 단계를 명확한 에러로 안내합니다). b3os 스킬을 쓰면 아래 준비물 설치·플러그인·페어링을 Claude가 대신 처리합니다.

Claude (주력·권장): Claude Code CLI 로그인 + tmux·bun. 텔레그램 플러그인은 user scope로 한 번만 설치하면 그 머신의 모든 Claude 봇이 공유합니다(봇마다 반복할 필요 없음).
OpenClaw / Hermes: 해당 런타임 CLI + 인증된 에이전트/프로필 1개(auth 시드) + python3(활성화 시 설정 편집에 사용).
플랫폼: 활성화는 지금 macOS 전용(launchd). Linux는 대시보드만 되고 봇 활성화는 안 됩니다.
활성화 스위치 APPROVAL_EXECUTION_ENABLED=1: install.sh가 "이 장비에서 팀원 활성화를 허용할까요?" 로 묻고 자동으로 설정합니다(본인 전용 맥에서만 y).

텔레그램 플러그인을 직접(수동) 설치하려면

telegram 플러그인은 user scope로 한 번만 설치하면 그 머신의 모든 Claude 봇이 공유합니다.

팀원 영입·활성화 → tmux 세션 claude-<id> 생성
tmux attach -t claude-<id> → /plugin install telegram@claude-plugins-official → user scope 선택 → /reload-plugins → detach(Ctrl-b 다음 d)

🔌 채널 연결

팀원은 채널로 사람과, 그리고 서로 대화합니다. 설정은 대시보드에서 하거나 Claude Code에게 시켜서 합니다 — .env 직접 편집은 필요 없습니다.

Telegram (1:1)

각 팀원은 자기 텔레그램 봇으로 1:1 DM을 받습니다. 봇 토큰을 팀원 영입 때 대시보드에 넣으면 끝입니다. 그때부터 그 팀원에게 DM으로 직접 일을 시킬 수 있습니다. *(1:1 대화는 아래 그룹방 설정의 라우터와 무관하게 동작합니다.)*

🛠️ 고급/AI 설치: 같은 값을 .env(CAPTURE_BOT_TOKEN · CAPTURE_GROUP_ID · ROUTER_ENABLED)로도 넣을 수 있지만, 일반 사용자는 위 대시보드만으로 충분합니다.

Slack (선택 — 텔레그램만 써도 됩니다)

Slack 연결은 선택입니다(텔레그램만으로 충분). 아래는 Slack 사이트에서 앱·토큰을 직접 만드는 과정입니다. App-Level Token(xapp-…, 봇을 소켓으로 연결하는 열쇠) 같은 Slack 전용 용어가 나오는데, 이 부분은 Slack 웹에서 사람이 직접 해야 하며 대시보드 위저드가 각 단계를 그림으로 안내합니다.

Slack은 Socket Mode로 붙습니다 — 공개 URL·웹훅 엔드포인트가 필요 없습니다.

대시보드 Settings → Slack 위저드를 엽니다.
안내되는 매니페스트로 앱 생성 (From a manifest — Socket Mode가 켜진 매니페스트) → 워크스페이스 선택.
Event Subscriptions → Enable Events ON → Subscribe to bot events → app_mention 추가 → Save Changes. (매니페스트에 이미 있어도 실제로 켜져 있는지 확인하세요 — 꺼져 있으면 봇이 멘션에 반응하지 않고 오류도 나지 않습니다)
App-Level Token (xapp-…, scope connections:write)을 발급해 대시보드에 붙여넣습니다. (메시지 전송용 봇 토큰 xoxb-…는 별도)
봇을 대상 채널에 초대합니다.

🛠️ @멘션이 없으면 봇에게 전달되지 않습니다. 서버는 멘션 이벤트만 받습니다. 멘션 없이 쓴 글은 들어가지 않고 오류도 나지 않으니, 답이 없을 때는 "무시"가 아니라 "안 들어간 것"일 수 있습니다.

자세한 절차는 docs/SLACK_SETUP.md.

채널은 텔레그램·슬랙 중 하나만 연결해도 됩니다.

💬 첫 지시 보내기

사람에게 말하듯 지시합니다.

@멘션: 특정 팀원에게 직접 맡깁니다.
답장(reply): 원문을 쓴 팀원이 이어받습니다.
일반 지시: 누가 맡을지 애매하면 라우터가 역할과 맥락을 보고 담당자를 고릅니다.

예시:

@bill 이 changelog 요약하고 중요한 변화만 알려줘.

긴 일은 owner·상태·설명·완료 기준이 있는 작업 카드로 남길 수 있습니다. 채팅이 지나가도 요청이 사라지지 않게 하기 위해서입니다.

📡 그룹방 설정 (선택 — 팀 협업) - 클로드 코드랑 진행하세요!!

여러 팀원이 하나의 그룹방에서 함께 일하게 하려면 System OP 봇을 둡니다(팀 라우터 역할 — 대시보드 라벨은 "시스템 OP", 토큰 필드는 "capture 봇 토큰"으로 같은 봇을 가리킵니다). 그룹에 올라온 모든 메시지를 받아 담당자에게 배정하는 역할입니다. (1:1 DM만 쓸 거면 건너뛰어도 됩니다.)

📖 팀이 내부적으로 어떻게 소통하는가 — 팀버스 동작원리, 주입문 형식(<external_message> 봉투 + 통신 가이드), 협업 프로토콜, 봇끼리 무한루프 방지, 리스타트 시 주입까지 실제 코드·템플릿·실사례로 정리: docs/TEAM_COMMUNICATION.md. (아키텍처 흐름도는 docs/COMMUNICATION_FLOW.md.)

op 봇 만들기 — @BotFather 에서 팀원 봇과 별개의 봇을 하나 더 만들어 토큰을 받습니다. (왜: op 봇은 팀원이 아니라 그룹 입구 + 운영 명령 전용입니다.)
그룹 만들고 초대 — 팀원들을 넣을 텔레그램 그룹을 만들고, op 봇과 각 팀원 봇을 초대합니다.
★op 봇을 그룹 관리자로 승격 — 가장 편한 방법★ — op 봇을 그룹 관리자로 올리면 privacy mode와 무관하게 모든 그룹 메시지를 받습니다. (대안: @BotFather → /setprivacy → op 봇 선택 → Disable.) (왜: privacy mode가 켜져 있으면(BotFather 기본값) 봇은 자기에게 온 명령·자기 멘션·자기 답장만 보고 일반 그룹 메시지를 못 받습니다 → 멘션 없는 지시나 다른 팀원 멘션이 라우터에 안 잡힙니다. 관리자는 privacy mode를 우회합니다.)
- ★팀원 봇도 그룹 관리자로 승격 — 👀 리액션을 받으려면 필수★ — 각 팀원 봇(claude/hermes/openclaw)을 그룹 관리자로 올리세요. (왜: 팀원이 지시를 받으면 원본 메시지에 네이티브 👀 리액션(수신 표시)을 붙이는데, 이건 봇이 그 메시지를 "볼 수 있어야" 가능합니다. 일반 참가자는 privacy mode 때문에 원본을 못 봐 message to react not found로 조용히 실패합니다 상세 동작: docs/GROUP_ROOM_ROUTING.md.)
대시보드 Settings ▸ 시스템 OP 패널에서 —
- capture 봇 토큰 붙여넣기 → 봇 연결 확인 버튼을 누르면 봇 username이 떠서 토큰이 정상인지 바로 확인됩니다.
- 그룹 chat_id (예: -1001234567890) — op 봇이 그룹에 들어간 상태에서 그룹에 아무 메시지나 하나 올린 뒤, Claude Code에게 "우리 그룹 chat_id 알려줘" 라고 하면 자동으로 찾아 설정합니다(내부적으로 op 봇이 이미 받은 그룹을 조회 — 그룹이 하나면 자동 지정). 직접 넣어도 됩니다 — 그룹에 @userinfobot을 잠깐 초대하면 chat_id를 알려줍니다.
- 라우터 토글 ON (즉시 반영)
확인 — 그룹에서 @팀원 멘션 또는 /status 를 보내 응답이 오면 준비 완료입니다. 자동감지가 그룹을 못 찾거나(3번 privacy mode를 확인) 응답이 없으면, 라우터가 OFF(기본값) 인지 먼저 봅니다 — OFF면 팀원이 그룹에서 응답하지 않고 결정만 shadow 로깅됩니다. 그룹 협업하려면 ON.

🔧 맥 부팅 후 안 뜰 때 (Trouble Shooting)

보통은 맥을 켜면 저절로 올라옵니다. 아래는 그게 안 됐을 때만 씁니다.

bash bin/team-os up       # 올린다
bash bin/team-os doctor   # 왜 안 뜨는지 본다
bash bin/team-os down     # 내린다

순서는 이렇게 — up 먼저, 그래도 안 되면 doctor.

`up` — 올린다

맥을 켰을 때 떠 있어야 할 것을 전부 올리고, 20초 뒤 결과를 보여줍니다.
서버·팀원·연동 다리가 모두 대상입니다. 팀원 이름은 설치마다 다르므로 이름을 고정하지 않고
자동실행 설정을 직접 읽어 찾습니다.

■ 올립니다
  · com.you.team-collab (정상)
  → com.you.claude-telegram-bill 등록
  · 서버 응답 정상
■ 결과
  ✓ 서버 정상 (팀원 12명)
  ✓ 자동실행 7개 전부 정상

  됐습니다. 텔레그램으로 팀원에게 말 거세요.

이렇게 나오면 끝입니다. 그 뒤엔 텔레그램으로 팀원에게 말을 걸면 됩니다.

이미 떠 있는 것은 건드리지 않습니다 — 둘로 뜨거나, 막 올라오던 걸 죽이지 않게.
"등록됨" 이 아니라 "지금 살아있음" 으로 판단합니다. 등록만 되고 죽어 있으면 다시 올립니다.
자동실행 등록 자체가 없으면 등록부터 하고 올립니다.
정해진 시각에 도는 예약 작업은 대상이 아닙니다 — 다시 등록하면 같은 일이 두 번 돕니다.
하나라도 못 살리면 성공이라고 말하지 않습니다 (종료 코드도 실패).
두 번 눌러도 안전합니다.

`doctor` — 왜 안 뜨는지 본다

up 으로 안 되면 이걸 돌리고, 나온 내용을 그대로 팀원에게 주세요.

■ 점검
  ✓ 서버 정상 (팀원 12명)
  ✗ 자동실행 7개 중 6개만 정상

■ 하나씩
  ✓ com.you.team-collab — 정상
  ✗ com.you.claude-telegram-bill — 등록은 됐는데 안 돌고 있음 → team-os up
  …

■ 마지막 오류 3줄
  …

`down` — 내린다

up 이 올리는 것을 전부 내립니다. 서버·팀원·연동 다리 모두입니다.
팀원은 자동실행만 내리면 세션이 계속 살아 있으므로 세션까지 같이 닫습니다.

맥을 끄기 전에 팀을 통째로 세울 때 씁니다. 다시 올릴 땐 team-os up.

그래도 안 되면

서버를 손으로 띄워서 화면의 오류를 그대로 보세요.

bun run src/server/index.ts

오류가 보이면 Ctrl+C 로 끄고, 그 내용을 팀원에게 주면 됩니다.

💡 직접 외우거나 적어둘 것이 없습니다. team-os 가 알아서 찾습니다.

자동실행 이름(com.<사용자>.…)은 설치마다 다릅니다 →
~/Library/LaunchAgents/*.plist 를 열어 안에 적힌 Label 을 그대로 읽습니다.

저장소 위치도 설치마다 다릅니다 →
이 스크립트가 <저장소>/bin/team-os 자리에 있으므로 자기 위치에서 알아냅니다.
바로가기(심링크)로 불러도 끝까지 따라갑니다.

스크립트를 저장소 밖으로 복사해서 쓰신다면 그때만 알려주세요:
TEAM_OS_REPO=<저장소 경로> team-os doctor

며칠 꺼뒀다가 켜면 — 밀린 예약 작업은 어떻게 되나

예약 작업은 디스크에 저장되므로 꺼도 없어지지 않습니다.

밀린 것이 쌓이지는 않습니다. 다음 실행 시각을 지금 기준으로 다시 잡고 지나간 차례를
채워 돌리지 않기 때문에, 30분마다 도는 작업을 사흘 꺼둬도 144번이 아니라 한 번 돕니다.

그래서 며칠 만에 켜시면 작업마다 한 번씩, 켠 직후에 몰려서 옵니다.

그게 시끄러우면 — 지난 것은 건너뛰게 할 수 있습니다 (기본은 꺼짐)

SCHEDULER_MISFIRE_GRACE_SEC=7200   # 2시간 넘게 지난 차례는 실행하지 않음

기본은 꺼져 있습니다. 켜면 조용해지지만 놓친 것이 조용히 없어집니다 —
한 번짜리 알림은 다음 차례가 없고, 주간 작업은 한 주가 통째로 빕니다.
시끄러운 쪽이 없어지는 쪽보다 낫다고 보아 원할 때만 켜는 값으로 두었습니다.

건너뛴 기록은 실행 이력에 skipped 로 남습니다.

켠 상태에서도 늦더라도 반드시 실행해야 하는 작업은 misfire_policy 를
catch_up_once 로 둡니다. 예약 알림은 만들 때 misfire_policy 로 지정할 수 있습니다.

🗑️ 삭제 (uninstall)

떠나실 땐 bash uninstall.sh 한 줄이면 됩니다. 확인 프롬프트 후 팀원 전원 오프보드 → 서버 정지·LaunchAgent 해제 → 데이터(team.db·.env·var/·team-media) 삭제까지 하고, 마지막에 repo 폴더 삭제를 안내합니다. (--yes 확인 생략 · --keep-data 데이터는 남기고 정지만.)

AI-driven이면 여러분의 Claude Code에게 "b3os 언인스톨해줘" 하면 이 스크립트를 실행합니다.

🧭 주요 기능

화면	역할
Team / Settings	팀 이름, 미션, 팀원, 역할, 런타임, 역량을 설정합니다.
Tasks	작업을 owner와 상태 기준으로 추적합니다. 긴 일은 카드로 남습니다.
Inbox / Threads	들어온 메시지, 라우팅 결정, 답변, 인계를 확인합니다.
Audit	왜 특정 팀원이 호출됐는지, 어떤 일이 있었는지 추적합니다.
Reports	나중에 다시 볼 가치가 있는 결과물을 보관합니다.
Docs	팀 운영 문서를 대시보드 가까이에 둡니다.
Topology	팀원, 런타임, 채널, 라우터 연결 상태를 한눈에 봅니다.
Proposals	규칙, 워크플로우, 제품 동작 변경을 검토하고 결정합니다.
Search	메시지, 작업, 리포트, 과거 결정을 검색합니다.

Topology view Tasks view

💡 왜 다른가

대부분의 AI 도구는 assistant 한 명과 대화하는 경험에 최적화돼 있습니다. b3os는 AI 작업을 팀 운영으로 봅니다.

그래서 세 가지 루프를 잇습니다.

실행: 누가 일하고 있고, 어떤 상태이며, 어떤 결과가 필요한가.
책임: 다음 응답·승인·인계의 owner가 누구인가.
학습: 반복되는 패턴이 규칙·리포트·제안·재사용 워크플로우로 남는가.

사용자가 내부 루프 이름을 외울 필요는 없습니다. 중요한 건 보이는 동작입니다. 팀은 누가 맡았는지 알고, 사람은 방향을 지휘하고, 끝나지 않은 일은 사라지지 않습니다.

🔀 런타임 중립

b3os는 특정 모델 회사나 특정 agent shell 하나에 묶이지 않습니다. 다만 공개판의 기본·권장 경로는 Claude 입니다 — 가장 많이 테스트됐고, 이미 쓰는 Claude 로그인을 그대로 재사용하므로 b3os 때문에 새로 결제할 것은 없습니다. (Claude 구독 자체는 필요합니다 — 시작 전 준비물 참고. 팀원 전원이 그 구독 하나를 나눠 씁니다.)

지금 연결 가능한 런타임

Claude (기본·권장): Claude Code 세션을 팀원으로 연결합니다. 준비물이 가장 적고 온보딩이 자동으로 진행됩니다.
OpenClaw (고급 · BYO): OpenClaw gateway/session 기반 에이전트를 연결합니다. 사용자가 런타임 CLI·인증을 직접 준비합니다.
Hermes (고급 · BYO): Hermes 계열 에이전트를 연결합니다. 사용자가 런타임 CLI·인증을 직접 준비합니다.

BYO(Bring Your Own) 런타임 준비 절차는 위 팀원 만들기 › 영입 전 준비 를 참고하세요. 두뇌가 바뀌어도 팀 운영 모델은 그대로입니다.

🔒 안전 모델

b3os는 사람이 지휘하는 시스템입니다. 에이전트가 조율하고 실행할 수는 있지만, 민감한 행동은 사람의 명시적 승인 뒤에 둡니다.

공개 운영 모델은 몇 가지 원칙을 따릅니다.

담당자 선택이 명확해야 합니다: 멘션, 답장, 직전 맥락, 라우터 결정.
외부 전송·공개 게시·삭제·credential·결제·서비스 재시작은 사람 승인 게이트를 둡니다.
메시지·인계·결정은 나중에 추적할 수 있어야 합니다.
오래 남을 규칙·워크플로우 변경은 proposal 흐름으로 검토합니다.

🧩 팀 스킬 (재사용 워크플로우)

반복되는 팀 작업은 재사용 스킬로 정리돼 있습니다. 대부분 셸/노드 스크립트라 특정 런타임에 묶이지 않고 동작합니다. 전체 목록과 상세는 docs/B3OS_SKILLS.md에 있습니다.

스킬	설명
b3os-bwf	과제 수행 워크플로우 — 계획 → 배정 → 실행 → 검증 → 보고 → 종료
b3os-task-loop	Tasks 칸반 · 진행 추적 · 인계 검증 · 작업루프 wake
b3os-team-inbox	팀 메시지 버스 — 전송 · 답장 · 인계 추적
b3os-github-workflow	변경을 PR로 — 격리 · 커밋 신원 · 팀 계정 PR · 검증 근거 기록 · 승인 · 머지 후 확인
b3os-team-learning-loop	주간 self-learning — 팀 정책 자가발전
b3os-team-member-lifecycle	팀원 온보딩 / lifecycle
b3os-harness-playbook	병렬 실행(harness) 플레이북
b3os-ai-code-safety	AI 생성·수정 코드 안전 체크리스트 — SOLID+Effects, 완료 전 side effect·동시성·멱등성 점검
b3os-slack-format	슬랙 메시지 포맷
b3os-telegram-file-delivery	텔레그램 파일 전송 (HTML·PDF·이미지·ZIP 등)
b3os-report	팀 표준 보고서 (MD → 반응형 HTML)
b3os-scheduler	durable 스케줄러 — cron·간격·1회성 리마인드 잡을 `team.db`에 등록, 서버 워커가 시각 맞춰 발화

🤝 기여하기

이슈·PR 환영합니다. 개발 환경 세팅, 보내기 전 확인할 것, PR 절차는 CONTRIBUTING.md에 있습니다.

큰 변경은 먼저 이슈로 이야기해 주세요. 다 만들고 나서 방향이 안 맞으면 서로 아깝습니다.
보안 취약점은 공개 이슈 대신 SECURITY.md의 절차를 따라주세요.

📄 License

라이선스는 Apache License 2.0 입니다 — 자세한 내용은 LICENSE 파일을 참고하세요.

b3os는 gd.on의 개인 프로젝트로 시작한 오픈소스입니다. 마음껏 쓰고 고치시되, 출처(gd.on)만 함께 남겨주시면 고맙겠습니다. 🙏

개인·상용 모두 자유롭게 쓰실 수 있습니다. 상용 서비스나 제품에 b3os를 쓰신다면 "Powered by b3os" 처럼 출처를 밝혀 주세요.

"b3os"·"b3rys" 이름과 로고는 b3rys의 상표입니다. 코드는 자유롭게 쓰시되, 이름·로고를 제품명이나 브랜딩에 쓰시려면 별도로 문의해 주세요.

🍎 그리고 미리 양해를… gd.on이 순전히 맥에서 개발한 탓에 b3os도 맥에 찰떡같이 최적화돼 개발·테스트됐습니다. 윈도우·리눅스 쓰시는 분들껜 지금은 좀 삐걱댈 수 있어요 — 죄송합니다 🙇 차차 넓혀가겠습니다. (그때까진 macOS가 제일 얌전해요.)

🖥️ 맥과 Claude Code 환경에서 개발돼 지원·테스트 범위가 작습니다. 개인 프로젝트인 점 양해 부탁드립니다.

🕘 시간대: 예약 잡(일일 과제 리뷰 등)은 기본이 한국 시간(Asia/Seoul)입니다. .env 의 B3OS_SCHEDULER_TIMEZONE 으로 바꿀 수 있고, 서머타임(DST)을 쓰는 지역도 지원합니다(예: America/New_York·Europe/Berlin). IANA 시간대 이름을 쓰세요.

🔌 원격 접근 — b3os 머신(맥미니)에 밖에서 붙는 법(Tailscale VPN + SSH·화면 공유): 원격 접근 가이드

🌐 대시보드를 도메인으로 열기 — dash.example.com 같은 주소로 대시보드를 여는 법(터널 Host 설정 · 신뢰 주소 등록): 가이드

b3rys-team-os

b3os (b3rys team os)

b3os는 agent execution loop 에 organization responsibility loop 를 결합한 AI team operating system 입니다.

📋 시작 전 준비물

🚀 짧게 보면

🧑‍💻 클로드 코드를 설치 동반자로 세팅하세요!! (권장 경로)

⚡ 가장 빠른 시작 — b3os 스킬 (권장)

사용자가 해야 되는 것 (AI가 "이건 직접 해주세요"라고 안내합니다)

🧰 빠른 시작 (스킬 없이 직접 설치)

👥 팀원 만들기

영입(활성화) 전 준비 — 런타임별 (Prerequisites)

🔌 채널 연결

Telegram (1:1)

Slack (선택 — 텔레그램만 써도 됩니다)

💬 첫 지시 보내기

📡 그룹방 설정 (선택 — 팀 협업) - 클로드 코드랑 진행하세요!!

🔧 맥 부팅 후 안 뜰 때 (Trouble Shooting)

`up` — 올린다

`doctor` — 왜 안 뜨는지 본다

`down` — 내린다

그래도 안 되면

며칠 꺼뒀다가 켜면 — 밀린 예약 작업은 어떻게 되나

그게 시끄러우면 — 지난 것은 건너뛰게 할 수 있습니다 (기본은 꺼짐)

🗑️ 삭제 (uninstall)

🧭 주요 기능

💡 왜 다른가

🔀 런타임 중립

🔒 안전 모델

🧩 팀 스킬 (재사용 워크플로우)

🤝 기여하기

📄 License

Yorumlar (0)

b3os (b3rys team os)

b3os는 agent execution loop 에 organization responsibility loop 를 결합한 AI team operating system 입니다.

📋 시작 전 준비물

🚀 짧게 보면

🧑‍💻 클로드 코드를 설치 동반자로 세팅하세요!! (권장 경로)

⚡ 가장 빠른 시작 — b3os 스킬 (권장)

사용자가 해야 되는 것 (AI가 "이건 직접 해주세요"라고 안내합니다)

🧰 빠른 시작 (스킬 없이 직접 설치)

👥 팀원 만들기

영입(활성화) 전 준비 — 런타임별 (Prerequisites)

🔌 채널 연결

Telegram (1:1)

Slack (선택 — 텔레그램만 써도 됩니다)

💬 첫 지시 보내기

📡 그룹방 설정 (선택 — 팀 협업) - 클로드 코드랑 진행하세요!!

🔧 맥 부팅 후 안 뜰 때 (Trouble Shooting)

up — 올린다

doctor — 왜 안 뜨는지 본다

down — 내린다

그래도 안 되면

며칠 꺼뒀다가 켜면 — 밀린 예약 작업은 어떻게 되나

그게 시끄러우면 — 지난 것은 건너뛰게 할 수 있습니다 (기본은 꺼짐)

🗑️ 삭제 (uninstall)

🧭 주요 기능

💡 왜 다른가

🔀 런타임 중립

🔒 안전 모델

🧩 팀 스킬 (재사용 워크플로우)

🤝 기여하기

📄 License

Yorumlar (0)

`up` — 올린다

`doctor` — 왜 안 뜨는지 본다

`down` — 내린다