discord-agent-bridge 0.4.1 → 0.6.0

package/README.ko.md

@@ -4,60 +4,53 @@
 
 > Self-hosted Discord bot that runs AI coding agents — Claude Code, Codex, and more — per channel. Role-based access, multi-server, extensible.
 
-**채널마다 Claude Code / Codex 같은 AI 코딩 에이전트를 붙여 쓰는 셀프호스팅 Discord 봇입니다.** 내 PC에서 실행되고, 역할 기반 권한 · 다중 서버 · 확장 가능 구조를 가집니다.
-
-- 현재 지원: **Claude Code**, **Codex**
-- 확장: 모드 플러그인 추가로 다른 에이전트(예: opencode) 연결 가능
-
-> ✅ **npm에 배포되어 있습니다.** `npx discord-agent-bridge` 로 바로 실행하거나(권장), 전역 설치·소스 빌드로도 쓸 수 있습니다. **Claude Code · Codex** 두 백엔드를 지원합니다.
+**Discord 채널 하나에 Claude Code(또는 Codex)를 붙여 쓰는 셀프호스팅 봇입니다.** 봇은 내 PC에서 돌고, npm에 배포되어 있어 `npm install -g` 한 번과 명령 세 줄이면 자동 실행까지 끝납니다.
 
 ---
 
-## 이게 뭐예요?
+## Why this?
 
-Discord 채널에서 대화하듯 메시지를 보내면, 내 컴퓨터에서 Claude Code(또는 Codex)가 그 프로젝트 폴더를 대상으로 작업해 주는 봇입니다.
-
-- **채널 = 세션 = 프로젝트 하나.** 채널을 만들 때 작업 폴더와 백엔드(Claude/Codex)를 정합니다.
-- **여러 서버**에 같은 봇을 초대해 쓸 수 있고, **서버/프로젝트마다 설정이 따로** 적용됩니다.
-- **역할(Role)로 누가 쓸 수 있는지** 통제합니다.
+- 🏠 **완전 셀프호스팅.** 봇이 내 PC에서 돕니다. 코드도, 세션도, CLI 토큰도 밖으로 안 나갑니다.
+- 📱 **책상 앞에 없어도 됩니다.** 지하철에서 폰으로 Discord에 지시만 던져 두세요. 스트리밍 응답, 툴 실행 로그, 권한 승인 버튼이 채널에 그대로 뜹니다.
+- 🗂️ **채널 하나 = 프로젝트 하나 = 세션 하나.** 채널마다 작업 폴더 · 백엔드 · 모델 · 권한 모드가 따로 붙습니다.
+- 👥 **팀 관전 친화적.** 같은 채널을 보는 사람은 세션 진행을 그대로 지켜봅니다. 3단계 역할(admin / execute / read-only)로 실제 실행 권한만 통제합니다.
+- 🔀 **Claude ⇄ Codex 즉시 전환.** `/mode` 한 방으로 백엔드를 바꿉니다.
+- ⚙️ **터미널과 동등한 기능.** 프로젝트의 `.claude/`, `.codex/` 설정을 그대로 읽어서 서브에이전트 · 스킬 · 훅 · MCP · 플러그인 명령까지 CLI와 똑같이 동작합니다.
 
 ---
 
 ## 준비물
 
 - **Node.js 20 이상**
-- 사용할 백엔드에 맞는 CLI가 **설치 + 로그인**되어 있어야 합니다:
-  - **Claude 모드** → [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 인증 (`claude` 로그인 또는 `ANTHROPIC_API_KEY`). 사용량/한도 패널을 보려면 **Claude Pro/Max 구독 로그인**이 필요합니다.
-  - **Codex 모드** → `codex` CLI 설치 + 로그인.
+- 쓰려는 백엔드에 맞춰 CLI가 **설치 + 로그인** 상태:
+  - **Claude 모드** → [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` 로그인 또는 `ANTHROPIC_API_KEY`)
+  - **Codex 모드** → `codex` CLI, 로그인까지
 - **Discord 봇 토큰** (아래 1단계에서 발급)
 
 ---
 
-## 1단계 — Discord 봇 만들기 (Developer Portal)
+## 1단계 — Discord 봇 만들기
 
-봇을 직접 하나 만들어야 합니다. 5분이면 됩니다.
+봇을 하나 직접 만들어야 합니다. 5분이면 됩니다.
 
-1. **[Discord Developer Portal](https://discord.com/developers/applications)** 접속 → 오른쪽 위 **New Application** → 이름 입력(예: `my-agent-bot`) → **Create**.
-2. 왼쪽 메뉴 **Bot** 탭 → **Reset Token** → 나오는 **토큰을 복사**해 안전한 곳에 보관.
-   - ⚠️ 이 토큰은 비밀번호입니다. 노출되면 즉시 **Reset Token**으로 재발급하세요.
+1. **[Discord Developer Portal](https://discord.com/developers/applications)** 접속 → 우측 상단 **New Application** → 이름 입력(예: `my-agent-bot`) → **Create**.
+2. 왼쪽 메뉴 **Bot** 탭 → **Reset Token** → 나오는 **토큰을 복사**해서 안전한 곳에 보관하세요.
+   - ⚠️ 이 토큰은 비밀번호나 다름없습니다. 노출되면 즉시 **Reset Token**으로 재발급하세요.
 3. 같은 **Bot** 탭 아래 **Privileged Gateway Intents**:
-   - ✅ **MESSAGE CONTENT INTENT** — **필수** (봇이 메시지 내용을 읽어야 함)
-   - ✅ **SERVER MEMBERS INTENT** — 권장 (역할 기반 권한 확인에 사용)
+   - ✅ **MESSAGE CONTENT INTENT** — **필수** (봇이 메시지 내용을 읽어야 합니다)
+   - ✅ **SERVER MEMBERS INTENT** — 권장 (역할 확인에 사용)
    - 켜고 **Save Changes**.
-4. 왼쪽 **OAuth2** 탭 → **Client ID(Application ID)** 복사 (셋업에 필요).
+4. 왼쪽 **OAuth2** 탭 → **Client ID(Application ID)** 복사.
 5. **초대 링크 만들기** — OAuth2 → **URL Generator**:
    - **Scopes**: `bot`, `applications.commands`
    - **Bot Permissions**: `Manage Channels`, `Send Messages`, `Embed Links`, `Attach Files`, `Read Message History`, `Create Public Threads`, `Send Messages in Threads`, `Manage Threads`, `Add Reactions`
-   - 생성된 URL을 브라우저에 붙여넣어 **내 서버에 초대**.
-   - (셋업 마법사가 이 초대 링크를 자동 생성해 주기도 합니다 — 2단계 참고.)
+   - 생성된 URL을 브라우저에 붙여넣어 **내 서버에 초대**하세요.
 
 ---
 
 ## 2단계 — 설치 & 실행
 
-### 설치 & 자동 실행 (권장)
-
-가장 간단한 방법입니다. 아래 세 줄이면 설치부터 재부팅 자동 실행까지 끝납니다. `service install` 이 현재 OS에 맞는 자동 실행을 알아서 등록합니다 — **macOS는 launchd, Linux는 systemd, Windows는 작업 스케줄러**.
+명령 세 줄이면 설치부터 재부팅 자동 실행까지 끝납니다. `service install` 이 현재 OS에 맞는 자동 실행을 알아서 등록합니다 — **macOS는 launchd, Linux는 systemd, Windows는 작업 스케줄러**.
 
 ```bash
 npm install -g discord-agent-bridge      # 설치
@@ -73,314 +66,54 @@ discord-agent-bridge service restart     # 재시작
 discord-agent-bridge service uninstall   # 등록 해제
 ```
 
-업그레이드는 최신 설치 후 재시작:
-
-```bash
-npm install -g discord-agent-bridge@latest
-discord-agent-bridge service restart
-```
-
-> ⚠️ **Windows 참고**: 작업 스케줄러 로그온 트리거로 등록되어 **로그인 시 자동 시작**됩니다(관리자 권한 불필요). 단, 크래시 시 자동 재시작은 보장되지 않습니다(macOS·Linux는 보장). `service install` 이 안 되면 아래 **수동 설정 — Windows (작업 스케줄러)** 를 참고하세요.
-
----
-
-아래부터는 `service install` 이 동작하지 않거나 직접 설정하고 싶을 때의 **수동 방법**입니다.
-
-### 수동 설정 — macOS (launchd)
-
-macOS 기본 서비스 관리자인 **launchd** 로 봇을 직접 실행합니다 — 로그인하면 자동 시작되고, 꺼지면 자동으로 되살아납니다.
-
-```bash
-# 1) 전역 설치 (아직이면 셋업도 한 번)
-npm install -g discord-agent-bridge
-discord-agent-bridge --setup      # 이미 설정했으면 생략
-
-# 2) 실행 래퍼 생성 — nvm의 default node를 자동으로 찾으므로 node 버전이 바뀌어도 그대로 동작
-mkdir -p ~/.discord-agent-bridge
-cat > ~/.discord-agent-bridge/run.sh <<'EOF'
-#!/bin/bash
-export NVM_DIR="$HOME/.nvm"
-[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
-nvm use default >/dev/null 2>&1 || nvm use node >/dev/null 2>&1
-exec discord-agent-bridge
-EOF
-chmod +x ~/.discord-agent-bridge/run.sh
-# nvm을 안 쓴다면 run.sh 는 `#!/bin/bash` 와 `exec discord-agent-bridge` 두 줄이면 됩니다(PATH에 node가 있어야 함).
-
-# 3) LaunchAgent 등록 파일 생성 ($HOME 는 파일을 만드는 시점에 절대경로로 치환됩니다)
-cat > ~/Library/LaunchAgents/com.discord-agent-bridge.plist <<EOF
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key><string>com.discord-agent-bridge</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/bin/bash</string>
-        <string>$HOME/.discord-agent-bridge/run.sh</string>
-    </array>
-    <key>EnvironmentVariables</key>
-    <dict><key>HOME</key><string>$HOME</string></dict>
-    <key>RunAtLoad</key><true/>
-    <key>KeepAlive</key><true/>
-    <key>StandardOutPath</key><string>$HOME/.discord-agent-bridge/agent.out.log</string>
-    <key>StandardErrorPath</key><string>$HOME/.discord-agent-bridge/agent.err.log</string>
-</dict>
-</plist>
-EOF
-
-# 4) 시작
-launchctl load -w ~/Library/LaunchAgents/com.discord-agent-bridge.plist
-
-# 5) 확인 — 'gateway ready' 가 뜨면 성공 (Ctrl+C 로 로그 보기만 빠져나옴, 봇은 계속 돎)
-tail -f ~/.discord-agent-bridge/agent.out.log
-```
-
-관리 명령:
-
-```bash
-launchctl list | grep discord-agent-bridge                                # 상태 (1열 PID, 2열 마지막 종료코드)
-launchctl unload ~/Library/LaunchAgents/com.discord-agent-bridge.plist    # 중지
-launchctl load  -w ~/Library/LaunchAgents/com.discord-agent-bridge.plist  # 시작
-```
-
 업그레이드:
 
 ```bash
 npm install -g discord-agent-bridge@latest
-launchctl unload ~/Library/LaunchAgents/com.discord-agent-bridge.plist
-launchctl load  -w ~/Library/LaunchAgents/com.discord-agent-bridge.plist
-```
-
-> ⚠️ nvm으로 **node 버전을 바꾸면** 그 버전에서 `npm install -g discord-agent-bridge` 를 한 번 실행하세요(nvm 전역 패키지는 버전별로 분리됩니다). 래퍼가 default node를 따라가므로 plist 자체는 고칠 필요가 없습니다.
-
-### 수동 설정 — Windows (작업 스케줄러)
-
-`discord-agent-bridge service install` 이 안 될 때 직접 등록하는 방법입니다.
-
-**명령어 (관리자 권한 불필요)** — 먼저 PowerShell에서 봇 실제 경로를 확인하세요:
-
-```powershell
-where.exe discord-agent-bridge      # 예: C:\Users\<나>\AppData\Roaming\npm\discord-agent-bridge.cmd
-
-# 위에서 확인한 경로로 로그온 시 자동 실행 등록
-schtasks /create /tn discord-agent-bridge /sc onlogon /tr "C:\Users\<나>\AppData\Roaming\npm\discord-agent-bridge.cmd" /f
-schtasks /query  /tn discord-agent-bridge      # 상태 확인
-schtasks /run    /tn discord-agent-bridge      # 지금 바로 시작
-schtasks /delete /tn discord-agent-bridge /f   # 해제
-```
-
-**GUI 로 하려면**: 시작 메뉴 → **작업 스케줄러** → **기본 작업 만들기** → 이름 `discord-agent-bridge`, 트리거 **로그온할 때**, 동작 **프로그램 시작** → 위 `where.exe` 로 확인한 `.cmd` 경로 입력 → 마침.
-
-> onlogon 작업은 **로그인 시** 실행이며 **크래시 시 자동 재시작은 보장하지 않습니다.** 크래시 자동 복구·로그인 전 실행까지 원하면 진짜 Windows 서비스가 필요합니다 — [nssm](https://nssm.cc/) 으로 등록하세요(관리자 권한 필요):
->
-> ```powershell
-> nssm install discord-agent-bridge "C:\Program Files\nodejs\node.exe" "C:\Users\<나>\AppData\Roaming\npm\node_modules\discord-agent-bridge\dist\cli.js"
-> nssm start discord-agent-bridge
-> ```
-
-### 수동 설정 — PM2 (Linux · Windows 대안)
-
-Linux·Windows에서는 [PM2](https://pm2.keymetrics.io/) 를 써도 됩니다(로그·재시작·상태 확인이 편리). **macOS에서는 PM2 대신 위 `service install`/launchd 를 쓰세요** — PM2의 fork 래퍼가 macOS에서 봇의 게이트웨이 연결을 막는 경우가 있습니다.
-
-```bash
-# 1) 전역 설치 (PM2가 안정적으로 실행할 커맨드가 있어야 함)
-npm install -g discord-agent-bridge
-
-# 2) 아직 셋업 안 했다면 한 번 실행
-discord-agent-bridge --setup
-
-# 3) PM2 설치
-npm install -g pm2
-
-# 4) PM2에 봇을 등록·실행
-pm2 start discord-agent-bridge --name discord-agent-bridge
-
-# 5) 현재 프로세스 목록을 스냅샷 저장 (재부팅 시 복구 대상)
-pm2 save
-
-# 6) 부팅 시 PM2 자동 시작 등록 (macOS는 launchd로 등록됨)
-pm2 startup
-# ↑ 출력되는 `sudo ...` 명령을 그대로 복사해 한 번 실행하세요.
-```
-
-일상적인 관리 명령:
-
-```bash
-pm2 status                          # 실행 상태
-pm2 logs discord-agent-bridge       # 실시간 로그
-pm2 restart discord-agent-bridge    # 재시작 (업그레이드 후에도 사용)
-pm2 stop discord-agent-bridge       # 중지
-pm2 delete discord-agent-bridge     # 등록 해제
-```
-
-PM2 상태에서 업그레이드:
-
-```bash
-npm install -g discord-agent-bridge@latest
-pm2 restart discord-agent-bridge
-```
-
-> ⚠️ nvm/asdf를 쓴다면, PM2가 부팅 시점에도 셸에서 쓰는 것과 **같은 `node`** 를 찾을 수 있어야 합니다. `which node`로 확인한 경로가 부팅 환경에서도 유효해야 합니다 — 아니면 재부팅 후 PM2가 봇을 못 띄웁니다.
-
-### npx로 실행 (빠르게 시험해보기)
-
-설치 없이 바로 한 번 띄워보고 싶을 때 쓰세요. `npx` 가 최신 버전을 받아 실행하며, 최초 실행이면 셋업 마법사가 먼저 뜬 뒤 이어서 봇이 시작됩니다. (터미널을 닫으면 봇도 종료됩니다 — 계속 켜두려면 위 PM2 방식을 쓰세요.)
-
-```bash
-# 최초 실행 — 셋업 마법사가 자동으로 뜬 뒤 이어서 봇이 시작됩니다.
-# (토큰/Client ID 입력, 인텐트 확인, 초대 링크 생성 — 기본값은 안 물어봄)
-npx discord-agent-bridge
-
-# 이후 실행 — 이미 설정돼 있으면 바로 봇이 시작됩니다.
-npx discord-agent-bridge
-
-# 다시 설정만 하고 싶을 때 (봇은 시작하지 않음)
-npx discord-agent-bridge --setup
-```
-
-전역 설치도 가능합니다: `npm install -g discord-agent-bridge` 후 `discord-agent-bridge` / `discord-agent-bridge --setup`.
-
-### 업그레이드
-
-새 버전이 나오면:
-
-```bash
-# npx 사용자 — @latest 를 붙이면 항상 최신을 받습니다(npx는 캐시를 쓸 수 있어요).
-npx discord-agent-bridge@latest
-
-# 전역 설치 사용자
-npm install -g discord-agent-bridge@latest
+discord-agent-bridge service restart
 ```
 
-설치된 버전 확인: `discord-agent-bridge --version`.
-
-**셋업 마법사(`--setup`)** 가 물어보는 것 — **토큰(비밀)만 터미널에서 입력**합니다. 그 외 값은 하나도 안 물어봅니다:
-1. Discord 봇 **토큰** (비밀 → 터미널에서만 붙여넣기)
-2. **Client ID**
-3. Message Content Intent 켰는지 확인
-4. 초대 URL 생성 → 서버에 초대
-
-> **역할도, 기본값도 터미널에서 안 정합니다.** 봇을 서버에 초대한 뒤 Discord에서 **`/config`** 명령으로 설정하세요:
-> - **역할 티어** — 역할 이름을 **클릭**해 지정(역할 ID 복사·개발자 모드 불필요). 지정 전에는 **모두 거부(deny-by-default)**.
-> - **기본값** — **기본 백엔드·모델·권한 모드·언어(locale)** 는 드롭다운에서 고르면 **바로 저장**되고, **Codex 기본 경로(codexHome)** 는 "Codex 경로 설정" 버튼 → 입력창(모달)에서 지정합니다. 언어는 `한국어 (ko)` / `English (en)` 중에서 선택합니다.
-
-설정은 `~/.discord-agent-bridge/` 에 저장됩니다(토큰 파일 권한 600). 역할·기본값은 서버별로 `servers/<guildId>.json` 에 저장됩니다.
+> ⚠️ **Windows 참고**: 작업 스케줄러 로그온 트리거로 등록되므로 **로그인 시 자동 시작**됩니다(관리자 권한 불필요). 크래시 시 자동 재시작은 보장하지 않습니다(macOS · Linux는 보장).
 
 ---
 
 ## 3단계 — Discord에서 사용하기
 
-봇이 서버에 들어오면 **컨트롤 채널(`#session-generator`) · 세션 카테고리 · 알림 채널(`#agent-status`)이 자동으로 생성**됩니다(봇에 채널 관리 권한이 있으면). 이후 순서: **`/config` → `/agent start`**.
+봇이 서버에 들어오면 **컨트롤 채널(`#session-generator`), 세션 카테고리, 알림 채널(`#agent-status`)이 자동으로 생성**됩니다(봇에 채널 관리 권한이 있는 한). 이후 흐름: **`/config` → `/agent start`**.
 
-1. **(자동)** 봇 시작·서버 초대 시 위 채널 구조가 생성됩니다. 관리자가 **`/init`** 으로 수동 재생성할 수도 있습니다(기존 채널은 재사용 — 중복 생성 없음).
-2. **`/config`** (관리자) → 역할 티어·기본값을 지정합니다. (서버 관리자(Administrator)는 역할 설정 없이도 항상 사용할 수 있습니다.)
-3. `#session-generator` 에서 **`/agent start`** → **마법사**가 순서대로 안내합니다:
-   **작업 폴더 선택 → 백엔드(Claude / Codex) → 모델 → 추론 수준 → 권한 모드**. 각 단계는 **"다음" 버튼**으로 넘어갑니다. 폴더 브라우저는 **상위/다른 볼륨까지 이동 · 새 폴더 생성 · 이전 세션 재개**를 지원합니다. 확인하면 프로젝트 폴더 이름으로 **전용 세션 채널(`proj-<폴더>`)이 새로 생성**되고 그 채널에 바인딩됩니다.
-4. 만들어진 세션 채널에서 **그냥 메시지로 대화**하면 됩니다. Claude 모드는 스트리밍 출력·툴 실행 스레드·권한 승인 버튼이 뜹니다.
-5. 필요할 때 명령어 사용.
+1. **(자동)** 봇 시작 또는 서버 초대 시점에 위 채널 구조가 생깁니다. 관리자가 **`/init`** 으로 수동 재생성해도 됩니다(기존 채널은 재사용).
+2. **`/config`** (관리자) — 역할 티어와 기본값을 지정합니다. 서버 관리자(Administrator)는 역할 설정 없이도 항상 사용할 수 있습니다.
+3. `#session-generator` 에서 **`/agent start`**. **마법사**가 순서대로 안내합니다: **작업 폴더 → 백엔드(Claude / Codex) → 모델 → 추론 수준 → 권한 모드**. 각 단계는 **"다음" 버튼**으로 넘어갑니다. 폴더 브라우저는 상위/다른 볼륨 이동, 새 폴더 생성, 이전 세션 재개까지 지원합니다. 확인하면 **전용 세션 채널(`proj-<폴더>`)** 이 새로 생기고 그 채널에 바인딩됩니다.
+4. 만들어진 세션 채널에서 **일반 메시지로 그냥 대화**하면 됩니다. Claude 모드는 스트리밍 응답, 툴 실행 스레드, 권한 승인 버튼이 뜹니다.
 
 ### 주요 명령어
+
 | 명령어 | 설명 |
 |---|---|
-| `/init` | (관리자) 컨트롤 채널 + 세션 카테고리 생성 (재실행 시 재사용) |
-| `/agent start` | 새 세션 시작 — 마법사 확인 시 전용 세션 채널을 새로 생성 |
+| `/init` | (관리자) 컨트롤 채널 + 세션 카테고리 생성 (기존이 있으면 재사용) |
+| `/agent start` | 새 세션 시작 — 마법사 확인 시 전용 세션 채널 생성 |
 | `/agent resume` | 이전 세션 이어하기 |
 | `/agent close` | 세션 종료 + 세션 채널 삭제 |
-| `/agent stats` | 활성 세션 · 세션 통계 · Claude 사용량 보기 (본인에게만 표시) |
+| `/agent stats` | 활성 세션 · 세션 통계 · Claude 사용량 (본인에게만 표시) |
 | `/mode <claude\|codex>` | 백엔드 전환 (⚠️ 새 대화로 시작 — 이전 맥락 미승계) |
 | `/mode perm <모드\|프로필>` | 권한 모드/프로필 전환 (세션 유지) |
 | `/stop` | 현재 세션 즉시 중단 (킬 스위치) |
 | `/stop-all` | (관리자) 모든 세션 중단 |
-| `/config` | (관리자) 역할 티어 + 기본값(백엔드·모델·권한 모드·언어·Codex 경로) 설정 — 역할은 **클릭**, 기본값은 드롭다운/모달에서 지정 |
+| `/config` | (관리자) 역할 티어 + 기본값(백엔드 · 모델 · 권한 모드 · 언어 · Codex 경로) 설정 |
+
+### 권한 모드
 
-### 권한 모드 (세션이 얼마나 자율적인지)
-- `default` — 도구 실행 전마다 **Allow/Deny 버튼**으로 확인 (가장 안전)
+- `default` — 툴을 실행할 때마다 **Allow/Deny 버튼**으로 물어봅니다 (가장 안전)
 - `acceptEdits` — 파일 수정은 자동 수락
-- `plan` — 먼저 계획만 세우고 실행은 보류
+- `plan` — 계획만 세우고 실행은 보류
 - `bypassPermissions` — 전부 자동 (신뢰하는 프로젝트에서만)
 
-(Codex는 CLI의 승인·샌드박스 모드로 매핑됩니다.)
+Codex는 자신의 승인/샌드박스 모드로 매핑합니다.
 
 ### 이벤트 알림 (`#agent-status`)
 
-여러 세션의 **작업 완료·에러**를 `#agent-status` 채널 한 곳에 모아 요약해 알려줍니다. `/config` → **🔔 알림 설정** 에서 켜기/끄기와 대상 채널을 바꿀 수 있습니다.
+여러 세션의 **작업 완료와 에러**를 `#agent-status` 채널 한 곳에 요약해 알려줍니다. `/config` → **🔔 알림 설정** 에서 켜기/끄기와 대상 채널을 바꿀 수 있습니다.
 
 ---
 
-## 권한 & 역할 설정 (중요)
-
-이 봇은 **당신 PC에서, 당신 계정 권한으로** 코드를 실행합니다. 즉 봇에게 명령할 수 있는 사람은 **당신 컴퓨터에서 명령을 실행할 수 있는 사람**입니다. 그래서 역할 통제가 필수입니다.
-
-- **역할 티어 3단계** — Discord에서 **`/config`** 로 역할 이름을 **클릭**해 지정합니다(역할 ID·개발자 모드 불필요). admin ⊇ execute ⊇ read-only:
-  - **admin** — 설정/`stop-all`/`config` 등 관리
-  - **execute** — 세션 시작·명령 실행
-  - **read-only** — 읽기만
-  - > `/config` 는 처음엔 **서버 관리자(Administrator)** 권한이 있는 사람만 열 수 있고(허용 목록이 비어 있어도 부트스트랩 가능), 이후엔 admin 티어도 사용할 수 있습니다.
-- **기본은 거부(deny-by-default)** — 허용 목록에 없는 사람은 아무것도 못 합니다. `/config` 로 지정하기 전에는 아무도 실행할 수 없습니다.
-- **프로젝트별 접근 제어(ACL)** — 특정 프로젝트를 지정한 역할/사람만 쓰게 할 수 있습니다.
-- **감사 로그** — 누가 언제 무엇을 했는지 `~/.discord-agent-bridge/audit/` 에 기록됩니다.
-
-> ⚠️ **보안 주의:** 신뢰하지 않는 서버에 봇을 초대하거나 execute 역할을 너무 넓게 주지 마세요. 작업 폴더 밖(예: `~/.ssh`)은 봇이 접근하지 못하도록 기본 차단되어 있습니다.
-
----
-
-## Claude 모드 vs Codex 모드
-
-| | Claude 모드 | Codex 모드 |
-|---|---|---|
-| 실시간 스트리밍 | ✅ | ❌ (최종 결과 위주) |
-| 툴 실행 스레드 | ✅ | ❌ |
-| 권한 승인 버튼 | ✅ | ❌ (승인/샌드박스 모드로 대체) |
-| 세션 이어하기 | ✅ | ✅ |
-| **사용량/한도 표시** | ✅ (5시간·주간·컨텍스트) | ❌ (Codex CLI 제약) |
-
-### 터미널에서 쓰던 거랑 똑같나요?
-
-- **Claude 모드** — 터미널의 `claude`와 **같은 엔진**(공식 Claude Agent SDK)을 사용합니다. 프로젝트의 `.claude/` 설정을 그대로 읽어 **서브에이전트·스킬·훅·MCP가 동일하게** 동작하도록 만듭니다. 달라지는 건 입력이 Discord 메시지, 출력이 임베드/스레드라는 **표현 방식**뿐입니다. (터미널에서 타이핑하는 TUI 전용 슬래시 명령은 그대로 치는 방식이 아니라 SDK 방식으로 처리됩니다.)
-- **Codex 모드** — `codex exec`(비대화형)로 구동합니다. 같은 Codex 엔진에 설정/MCP를 로드하며, **훅(SessionStart/UserPromptSubmit/Stop 등)도 비대화형 모드에서 정상 발동함을 실측 확인**했습니다. 다만 승인 방식은 인터랙티브 모드와 다르게 매핑됩니다(아래 권한 모드 참고).
-
-### 커스텀 슬래시 명령 / 스킬 / 플러그인 명령
-
-세션 채널에 보내는 메시지는 가공 없이 그대로 Claude/Codex에 전달되므로, **`.claude/commands/`·`.claude/skills/`(Claude) 또는 `.codex/skills/`(Codex)에 정의된 명령·스킬, 그리고 플러그인이 설치한 명령**도 터미널과 똑같이 `/이름` 을 그대로 타이핑하면 동작합니다(Claude/Codex 실제 CLI로 실측 검증됨). Discord 자체 슬래시 명령(`/agent`, `/config` 등)과는 충돌하지 않습니다 — 세션 채널의 일반 텍스트 메시지이기 때문입니다.
-
----
-
-## 설정 파일 위치
-
-```
-~/.discord-agent-bridge/
-├─ config.json            # 봇 토큰·Client ID·기본값·한도 (권한 600)
-├─ servers/<guildId>.json # 서버별 역할 티어·기본값 · 채널 구조(control/sessions/status) ID · 알림 설정 (권한 600)
-├─ state.json             # 채널↔세션 바인딩 (재시작 후 자동 복구)
-└─ audit/audit.jsonl      # 감사 로그
-```
-설정은 **전역 → 서버 → 프로젝트** 순으로 덮어써집니다.
-
----
-
-## 문제 해결
-
-- **봇이 메시지에 반응하지 않아요** → Developer Portal에서 **Message Content Intent**가 켜져 있는지 확인.
-- **슬래시 명령이 안 보여요** → 초대 시 `applications.commands` 스코프를 포함했는지 확인(등록에 몇 분 걸릴 수 있음).
-- **권한 오류로 채널 생성 실패** → 봇에게 `Manage Channels` 권한이 있는지 확인.
-- **사용량 패널이 안 떠요** → Claude Pro/Max **구독 로그인**(`~/.claude`) 상태여야 합니다. API 키만 쓰면 이 패널은 숨겨집니다(정상).
-- **"권한이 없습니다: No authorized role for this actor (fail-secure)."** → 접속한 계정에 허용 목록(admin/execute/read-only)에 등록된 역할이 하나도 없다는 뜻입니다. 기본이 거부(deny-by-default)라 이렇게 나옵니다. 아래 중 하나로 해결하세요:
-  1. **가장 간단** — 그 계정에 Discord **서버 관리자(Administrator)** 권한을 부여. 서버 관리자는 허용 목록과 무관하게 admin 티어로 무조건 통과됩니다.
-  2. **이미 지정된 역할 부여** — Discord 서버의 구성원 화면에서, `/config`에 티어로 이미 등록되어 있는 역할을 그 계정에 붙여줍니다.
-  3. **역할을 티어에 추가** — 관리자 계정에서 `/config` → **역할 티어** 로 들어가, 그 계정이 가진 역할을 원하는 티어(admin/execute/read-only)에 클릭해 추가합니다.
-
----
-
-## 개발
-
-```bash
-npm install
-npm run dev         # tsx watch (개발 모드)
-npm run typecheck   # 타입 검사
-npm run test        # 테스트 (vitest)
-```
-
-## 라이선스
-
-MIT
+License: MIT