discordo

Discord 위에서 Claude Code 와 Codex CLI 세션을 멀티유저 / 멀티채널로 오케스트레이션하는 봇.

스레드 또는 채널 하나 = AI 에이전트 세션 하나. 슬래시 명령으로 세션을 시작하면 이후 모든 메시지가 AI로 라우팅됩니다. 에이전트들은 서로 대화하고, 작업을 위임하고, 브로드캐스트로 공지를 받을 수 있습니다.

npm i -g @leessju/discordo
discordo setup        # 10단계 설치 마법사

→ 자세한 설치 방법은 SETUP.md 를 참조하세요. (macOS · Linux · Windows WSL2 · Windows 네이티브 지원)

목차

1. 멀티채널 에이전트
2. 스레드 기반 세션
3. 지속 대화 — 세션 시작 후 바로 채팅
4. 에이전트 간 대화 — #thread-name 단축 문법
5. Delegate — 비동기 작업 위임
6. Task — 구조화된 작업 지시
7. Broadcast — 전체 에이전트 공지
8. 외부 REST API
9. 슬래시 명령 전체 목록
10. 권한 체계
11. GBrain — 장기 메모리 & 인테그레이션
12. Feature Flags
13. 아키텍처

1. 멀티채널 에이전트

채널 또는 스레드 하나가 독립된 에이전트 세션입니다. 여러 채널에서 서로 다른 작업을 동시에 실행할 수 있습니다.

#channel-frontend   → Claude 세션 (React 작업)
#channel-backend    → Claude 세션 (API 작업)
#channel-review     → Codex 세션 (코드 리뷰)

각 세션은 독립된 컨텍스트를 유지하며 서로 간섭하지 않습니다. 어드미션 큐가 채널별·유저별 동시 실행 수를 제한하여 리소스를 보호합니다.

2. 스레드 기반 세션

채널 내에서 스레드를 만들어 여러 작업을 격리할 수 있습니다. 스레드마다 별도의 Claude 인스턴스가 실행되므로 컨텍스트 오염 없이 병렬 작업이 가능합니다.

#dev-channel
 ├── thread: auth-refactor   → Claude (인증 리팩터링)
 ├── thread: bug-fix-#123    → Claude (버그 수정)
 └── thread: perf-audit      → Codex (성능 분석)

세션 시작:

/session start auth-refactor claude workdir:/home/user/myapp

옵션:

| 옵션 | 설명 | |---|---| | name | 세션 이름 (에이전트 식별자로 사용) | | runtime | claude 또는 codex | | workdir | 작업 디렉터리 (절대 경로) | | model | 모델 ID 오버라이드 (예: claude-opus-4-5) | | extra | 추가 CLI 인수 JSON 배열 (예: ["--allowed-tools=Bash,Edit"]) |

3. 지속 대화 — 세션 시작 후 바로 채팅

세션이 시작된 스레드에서는 모든 메시지가 자동으로 AI로 라우팅됩니다. 봇을 멘션하거나 슬래시 명령을 쓸 필요가 없습니다. 대화 기록이 컨텍스트로 유지됩니다.

[스레드: bug-fix-#123]

사용자: 이 함수가 null을 반환하는 이유가 뭐야?
봇:     코드를 분석해보겠습니다...

사용자: 그럼 테스트도 같이 써줘
봇:     네, 테스트 파일을 작성합니다...

사용자: /cancel   ← 진행 중 작업만 취소, 세션은 유지
사용자: 다시 처음부터 설명해줘   ← 계속 대화 가능

세션 초기화 없이 대화 기록만 리셋:

/session clear

멀티유저 협업 — 스레드에 여러 명 초대

스레드에 팀원을 초대하면 여러 명이 동시에 같은 AI와 대화할 수 있습니다. 각 메시지는 [@username] 형식으로 발화자가 표시되어 AI가 누가 무슨 말을 했는지 구분합니다.

[스레드: auth-refactor]  ← alice, bob, carol 모두 초대됨

[@alice]: 인증 흐름 전체 설명해줘
봇:       현재 구현은 JWT 기반으로...

[@bob]:   refresh token 만료 처리는 어떻게 돼?
봇:       만료 시 /auth/refresh 엔드포인트에서...

[@carol]: 그 부분 테스트 커버리지 확인해줘
봇:       현재 커버리지를 확인합니다...

AI는 대화 히스토리에서 각 발화자를 구분하므로, 팀 전체가 하나의 AI 세션을 공유하며 자연스럽게 협업할 수 있습니다.

초대 방법:

1. Discord 스레드 상단 → "멤버 추가" 클릭
2. 팀원 검색 후 추가
3. 추가된 팀원이 메시지를 보내면 바로 AI와 대화 시작

채널 모드에서 봇 멘션 없이 모든 채널 메시지를 AI로 전달하려면:

# ~/.discord-orchestrator/.env
OMC_CHANNEL_INCLUDE_BYSTANDERS=true

4. 에이전트 간 대화 — #thread-name 단축 문법

메시지 안에서 #에이전트이름 질문 형식을 사용하면, 현재 에이전트가 지정된 에이전트에게 질문을 전달하고 응답을 받아옵니다.

[스레드: frontend]
사용자: #backend API 엔드포인트 목록 알려줘

→ frontend 에이전트가 backend 에이전트에게 질문을 전달
→ backend 에이전트가 응답을 반환
→ frontend 에이전트가 해당 응답을 컨텍스트로 활용

타겟 해석 순서:

1. 정확한 threadId 매칭
2. 세션 레이블 매칭 (/session start [name]에서 설정한 이름)
3. agent-labels.json 레이블 매칭

이 기능은 인간 개입 없이 에이전트들이 서로 협업할 수 있게 해줍니다.

5. Delegate — 비동기 작업 위임

/delegate 는 다른 에이전트 스레드에 fire-and-forget 방식으로 작업을 위임합니다. 위임자는 결과를 기다리지 않고 즉시 다음 작업을 계속합니다.

/delegate target:backend task:사용자 인증 API 엔드포인트 추가해줘

• 타겟 에이전트가 오토컴플리트로 표시됩니다
• 작업 완료 여부는 타겟 스레드에서 확인
• 체인 ID 로 추적 가능 (/show-trace chainId)

/show-trace abc123def456   ← 위임된 작업의 실행 체인 추적

6. Task — 구조화된 작업 지시

/task 는 작업 상태를 추적하는 구조화된 협업 도구입니다. 담당자가 명시적으로 수락/완료해야 하므로 책임 소재가 명확합니다.

작업 할당

/task assign to:backend title:사용자 인증 API 구현 description:JWT 기반, refresh token 포함

작업 상태 흐름

pending → accepted → in_progress → done
                  ↘ rejected
       ↘ cancelled

담당자 명령

/task accept     ← 작업 수락
/task reject     ← 작업 거부 (사유 입력)
/task done       ← 완료 보고
/task cancel     ← 취소

상태 확인

/task status     ← 내가 관련된 태스크 목록

7. Broadcast — 전체 에이전트 공지

모든 활성 에이전트 세션에 동시에 메시지를 전송합니다.

/broadcast text:오늘 오후 3시에 배포합니다. 작업 중인 기능은 완료 후 커밋해주세요.

현재 스레드를 제외한 모든 활성 세션의 아웃박스에 메시지가 전달됩니다. 각 에이전트는 다음 요청 처리 시 공지를 컨텍스트로 수신합니다.

8. 외부 REST API

봇은 localhost:7707에서 HTTP API를 제공합니다. 외부 서비스나 스크립트에서 특정 에이전트 세션에 직접 접근할 수 있습니다.

GET /healthz — 시스템 상태

curl -s localhost:7707/healthz | python3 -m json.tool

응답 예시:

{
  "activeSessions": 3,
  "queuedCount": 0,
  "cliProcessCount": 3,
  "rssBytes": 142606336,
  "restartCount": 1,
  "tokenStatus": { "valid": true, "expiresIn": "3h 42m" },
  "flags": {
    "gbrain_enabled": false,
    "autonomous_inter_agent": false
  }
}

POST /mcp/{threadId}/call — 특정 스레드 MCP 도구 호출

특정 에이전트 스레드의 MCP 도구를 외부에서 직접 호출하고 결과를 받습니다.

curl -s -X POST localhost:7707/mcp/1234567890123456789/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "read_file",
    "args": { "path": "/home/user/myapp/src/index.ts" }
  }'

응답:

{
  "ok": true,
  "result": "..."
}

POST /dev/message — 스레드에 메시지 주입 (개발용)

Discord 없이 특정 스레드에 메시지를 전송하고 AI 응답을 동기적으로 받습니다.

curl -s -X POST localhost:7707/dev/message \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "1234567890123456789",
    "content": "현재 작업 중인 파일 목록 알려줘"
  }'

응답:

{
  "ok": true,
  "text": "현재 작업 중인 파일은..."
}

이 엔드포인트는 개발·테스트 전용입니다. 프로덕션에서는 Discord를 통해 상호작용하세요.

9. 슬래시 명령 전체 목록

Discord에서 Owner Role을 가진 사용자가 사용 가능한 명령입니다.

세션 관리

| 명령 | 설명 | 권한 | |---|---|---| | /session start <name> <runtime> | 새 세션 시작 (claude/codex) | member+ | | /session stop <name> | 현재 세션 종료 | member+ | | /session clear | CLI 세션 초기화 (설정 유지) | member+ | | /session list | 활성 세션 목록 | member+ | | /cancel | 진행 중 작업 취소 | member+ | | /resume | 재시작 후 세션 재개 | member+ | | /attach <thread> | 다른 스레드 연결 | member+ |

작업 도구

| 명령 | 설명 | 권한 | |---|---|---| | /diff | 워크트리 변경사항 표시 | member+ | | /cd <path> | 작업 디렉터리 변경 | member+ | | /model <name> | 세션 모델 변경 | member+ | | /skill <name> | 등록된 스킬 호출 | member+ | | /raw <text> | 원시 텍스트 전송 | member+ | | /show-trace <chainId> | 작업 체인 추적 | member+ | | /wait | 큐 위치 확인 | member+ |

에이전트 간 협업

| 명령 | 설명 | 권한 | |---|---|---| | /delegate <target> <task> | 다른 에이전트에 비동기 위임 | owner | | /broadcast <text> | 모든 활성 세션에 공지 | owner | | /task assign | 다른 스레드에 구조화된 작업 지시 | member+ | | /task status | 내 태스크 상태 | member+ | | /task accept\|reject\|done\|cancel | 태스크 상태 변경 | assignee |

관리

| 명령 | 설명 | 권한 | |---|---|---| | /permission set <user> <tier> | 권한 부여 | owner | | /permission show <user> | 권한 조회 | member+ | | /permission list | 멤버십 목록 | owner | | /health | 시스템 상태 | public | | /config | 봇 설정 조회/변경 | owner | | /brain | GBrain 메모리 조회 (GBrain 활성 시) | member+ |

10. 권한 체계

| 티어 | 설명 | |---|---| | owner | Owner Role을 가진 사용자. 모든 명령 사용 가능 | | member | /permission set @user member로 추가된 사용자 | | guest | 제한된 읽기 권한 | | public | /health 등 공개 명령만 | | blocked | 모든 봇 상호작용 차단 |

기본 사용 흐름

# 1. owner가 팀원에게 권한 부여
/permission set @alice member

# 2. alice가 세션 시작
/session start mywork claude

# 3. 이후 스레드에서 자유롭게 대화
alice: 이 코드의 버그를 찾아줘
봇: 코드를 분석합니다...

# 4. 특정 사용자 차단
/permission set @baduser blocked

11. GBrain — 장기 메모리 & 인테그레이션

GBrain은 봇에 장기 메모리 코어와 외부 서비스 연동을 추가하는 선택 기능입니다.

기능

• PGLite 메모리: 대화 내용을 임베딩 기반으로 저장·검색
• 컨텍스트 주입: 관련 과거 대화를 자동으로 Claude 프롬프트에 주입
• /brain 슬래시 명령으로 메모리 직접 조회·삭제
• Gmail 읽기: 이메일을 메모리에 수집
• Calendar 읽기: 일정을 메모리에 수집
• X(Twitter) 읽기: 트윗을 메모리에 수집

활성화

discordo setup 8단계에서 설정하거나, .env에서 직접:

# ~/.discord-orchestrator/.env
OMC_GBRAIN_ENABLED=1          # GBrain 활성화
OMC_GBRAIN_BRAIN_SLASH=1      # /brain 명령 활성화
OMC_GBRAIN_INTEGRATIONS=1     # Gmail/Calendar/X 수집 활성화

# Gmail OAuth (Google Cloud Console에서 발급)
GMAIL_OAUTH_CLIENT_ID=your-client-id
GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
GMAIL_OAUTH_REFRESH_TOKEN=your-refresh-token

설정 후:

discordo restart

자율 인터에이전트 (고급)

OMC_AUTONOMOUS_INTER_AGENT=1  # 에이전트 간 위임 시 승인 게이트 제거

⚠️ 활성화 시 봇이 사용자 승인 없이 다른 에이전트에 작업을 위임합니다. 비용이 예상보다 높을 수 있습니다.

12. Feature Flags

~/.discord-orchestrator/.env에서 "1" 값으로 활성화:

| 플래그 | 기능 | |---|---| | OMC_GBRAIN_ENABLED | PGLite 메모리 코어 + RAG 컨텍스트 | | OMC_GBRAIN_BRAIN_SLASH | /brain Discord 명령 등록 | | OMC_GBRAIN_INTEGRATIONS | Gmail/Calendar/X 읽기 수집 | | OMC_AUTONOMOUS_INTER_AGENT | 에이전트 간 자율 위임 (승인 없음) | | OMC_MULTITENANT | 멀티 프린시펄 + 프린시펄별 쿼터 | | OMC_CHANNEL_INCLUDE_BYSTANDERS | 채널의 모든 메시지 처리 (기본: false) |

13. 아키텍처

Discord Guild
  채널/스레드 = 세션 단위
        │
        ▼
┌─────────────────────────────────────────────┐
│        discordo (Node.js + PM2)              │
│                                              │
│  Discord client → Skill registry            │
│       ↓               ↓                     │
│  Session-key      Permission gate            │
│  (thread/channel) (4-tier)                  │
│                       ↓                     │
│               Admission queue               │
│               (per-user/channel cap)        │
│                       ↓                     │
│             Runtime adapters                │
│             (Claude / Codex)                │
│                       ↓                     │
│   Token-refresh-daemon → spawn(claude)      │
│   (5분 주기, 만료 4시간 전 자동 갱신)          │
│                                              │
│  Inter-agent bus (delegate / consult /      │
│  broadcast) · MCP server registry           │
│                                              │
│  SQLite(WAL) · GBrain(PGLite)               │
│  REST API (localhost:7707)                  │
└─────────────────────────────────────────────┘

설치

→ SETUP.md 에서 단계별 설치 가이드를 확인하세요.

관련 문서

• SETUP.md — 설치 가이드 (봇 생성 · setup 마법사 · 트러블슈팅)
• docs/AUTH.md — OAuth 인증 deep dive (토큰 갱신, 멀티 머신 충돌 방지)
• docs/FLAGS.md — Feature flags 운영자 레퍼런스

라이선스

MIT