hermes-cli-bridge

Discord CLI 브리지 패키지. 기존 저장소와 플러그인의 역사적 이름은 codex-discord이며, 현재 유지 저장소는 usermrk/hermes-agy-claude-cli-discord, npm 배포 패키지는 hermes-cli-bridge이다. 현재 준비 중인 npm 공개 버전은 0.1.3이다.

이 프로젝트는 netwaif/codex-discord를 기반으로 확장되었으며, 원본 MIT 저작권 표기는 LICENSE에 유지한다.

이 패키지는 CLI 본체를 Hermes 폴더로 복사하지 않는다. agy·Claude CLI의 기본 설치 위치와 인증 상태를 유지하고, 실행 파일 경로만 탐지해 브리지에서 사용한다.

npm 배포판 설치

공개 npm 패키지는 다음 명령으로 설치할 수 있다.

npm install hermes-cli-bridge

설치된 CLI 경로 탐지 도구를 실행하려면 다음 명령을 사용한다.

npx hermes-bridge-check

npm 페이지: https://www.npmjs.com/package/hermes-cli-bridge

소스에서 실행

1. https://discord.com/developers/applications 에서 앱 생성 → Bot 추가
2. Bot 설정에서 MESSAGE CONTENT INTENT 활성화 (필수)
3. OAuth2 > URL Generator: scope bot, 권한 Send Messages, Read Message History → 서버에 초대
4. .env.example을 .env로 복사하고 토큰·사용자ID·작업폴더 기입

실행

npm install
npm start

동작

• allowlist 사용자의 메시지만 처리, 일반 headless 경로는 각 Discord 메시지마다 자기 봇 멘션을 새로 요구하며 이전 메시지의 멘션을 상속하지 않음
• 일반 headless 경로에서 멘션 없는 후속 메시지는 무시하고, 다른 봇 멘션은 가로채지 않음
• 봇 협업은 기본적으로 차단되며, ALLOW_BOT_MENTIONS=true와 TRUSTED_BOT_IDS를 함께 설정한 경우에만 등록된 봇의 현재 본문 인라인 멘션을 trigger로 처리함
• 답글 자동 멘션과 코드 블록·인라인 코드·인용문 속 <@ID>는 실제 멘션으로 인정하지 않음
• iteration N/150, Redirected current run, Working, Compressing context 등 자동 상태·리다이렉션 메시지는 실행하지 않음
• 채널→세션 매핑은 data/sessions.json에 저장 (재시작해도 대화 유지)
• Codex는 항상 -s workspace-write 샌드박스로 실행 (전역 config 무관)
• 세션을 새로 시작하려면 data/sessions.json에서 해당 채널 항목 삭제

라이브 TUI 모드 (3자 대화)

.env에 TUI_PANE(예: ai:codex-live)과 TUI_CHANNEL_ID를 지정하면 그 채널은 headless 대신 살아있는 codex TUI 세션과 연결된다.

• 준비: 해당 tmux pane에서 codex를 켜고 메시지를 한 번 보내 세션 파일을 만들어 둔다
• 코덱스 호명: 봇을 멘션하거나 메시지를 코덱스로 시작 (예: "코덱스야 a.py 만들어줘")
• 호명 없는 발언·다른 봇(Claude)의 발언은 쌓였다가 다음 호명 때 [화자] 라벨로 함께 전달된다
• Codex의 모든 답변(터미널에서 직접 친 것 포함)이 채널로 릴레이된다
• 과정 구경: TUI pane 화면 그대로
• Claude와의 3자 대화: Claude 세션 쪽 CLAUDE.md에 "응답 전 fetch_messages로 최근 채널 히스토리를 확인하라"를 넣어야 Claude가 코덱스 발언을 본다
• 데몬 재시작 중·트리거 이전의 TUI 턴은 릴레이되지 않음 (tail은 연결 시점 이후만)
• TUI 세션에서 터미널로 직접 작업한 내용도 전부 채널로 방송됨 — 사적 작업은 다른 세션에서
• 권장: TUI 세션 첫 메시지로 "[화자] 라벨이 붙은 여러 사람의 대화가 들어오고 네 답은 Discord로 중계된다"고 프라이밍

파일 첨부 (양방향)

• Discord → Codex: 메시지에 파일을 첨부하면 워크스페이스 uploads/에 저장되고, 본문 끝에 (첨부 파일: uploads/이름) 주석이 붙어 Codex에게 전달된다 (headless·TUI 공통, 다운로드 상한 25MB)
• Codex → Discord: Codex가 답변에 [[첨부: 경로]] 한 줄을 포함하면 봇이 그 파일을 채널에 첨부한다
  • 경로는 워크스페이스 기준 상대 경로만 허용 (밖 경로·심링크 탈출은 거부, 상한 10MB)
  • 워크스페이스 밖 파일을 보내려면 Codex가 먼저 워크스페이스 안으로 복사해야 한다
  • TUI 모드에서는 프라이밍에 이 규칙을 알려줘야 한다: "파일을 채널에 첨부하려면 답변에 [[첨부: 워크스페이스 상대경로]] 한 줄을 넣어라"

Gemini(Antigravity CLI) 인스턴스 (선택)

같은 코드로 Gemini도 별도 봇으로 병행 운영할 수 있다 (엔진: agy — Antigravity CLI):

1. Discord 봇 계정을 하나 더 만들고 (예: "Gemini Bot") 토큰 발급
2. .env.gemini.example을 .env.gemini로 복사해 채우기 (ENGINE=agy, DATA_DIR=data-gemini 유지)
3. bash scripts/install.sh 재실행 → com.codex-discord.gemini 데몬이 추가 등록됨 (수동 실행: npm run start:gemini)

동작 방식: 첫 턴은 agy --new-project로 작업폴더를 워크스페이스로 잡고, 이후 --conversation <id>로 채널별 대화를 이어간다. 도구 실행은 --sandbox 안에서 자동 승인된다 (headless는 승인 프롬프트를 띄울 수 없어 필수). 라이브 TUI 모드는 codex 전용 — agy 인스턴스에서 TUI 변수는 무시된다.

참고: Gemini CLI(공식 gemini)는 개인 OAuth 지원이 종료되어(IneligibleTierError) 엔진으로 채택하지 않았다 (2026-07-24 실측).

CLI 경로 탐지 (agy/Claude)

브리지는 CLI 본체를 Hermes 폴더로 복사하지 않는다. 기본 설치 위치와 사용자의 PATH를 유지하면서 다음 순서로 실행 파일을 찾는다.

1. AGY_BIN 또는 CLAUDE_BIN 환경변수
2. PATH의 실행 파일
3. Linux/macOS 기본 위치 (~/.local/bin, /usr/local/bin)

심볼릭 링크인 경우 링크 경로와 실제 대상 경로를 모두 확인해 보고한다. 설치·업데이트는 각 CLI의 원래 설치 방식이 담당하고, 브리지 서비스는 탐지된 절대 경로를 사용한다.

npm run check:cli

예시 출력:

agy: /root/.local/bin/agy [PATH]
claude: /root/.local/bin/claude → /usr/local/lib/node_modules/... [PATH]

운영

• 부팅 자동 기동(macOS): .env를 채운 뒤 bash scripts/install.sh 한 번 — 경로 자동 탐지(node·tmux·codex) 후 LaunchAgent 2개를 생성·등록한다 (멱등, 재실행 = 재설치)
  • com.codex-discord.tui → 로그인 시 scripts/tui-up.sh 실행: 전용 tmux 세션 codex-live에 codex TUI 기동 + 더미 턴 1회(롤아웃 파일 생성용)
  • com.codex-discord.daemon → 데몬 상주(KeepAlive — 죽거나 부팅 직후 네트워크 미연결로 로그인 실패해도 자동 재시작)
• 플러그인으로 설치 (동봉된 setup 스킬이 봇 생성부터 자동 기동 등록까지 대화로 안내 — 마지막에 "코덱스 디스코드 설치해줘"):
  • Claude Code: /plugin marketplace add usermrk/hermes-agy-claude-cli-discord → /plugin install codex-discord
  • Codex CLI: codex plugin marketplace add https://github.com/usermrk/hermes-agy-claude-cli-discord → codex plugin add codex-discord@codex-discord
  • 규칙 각인(라벨 금지·[[첨부:]])은 워크스페이스 AGENTS.md가 담당 — 세션마다 프라이밍 입력 불필요
  • 낮에 TUI가 죽으면 npm run tui:up 한 줄로 복구 (멱등 — 떠 있으면 아무것도 안 함)
  • TUI 구경: tmux attach -t codex-live (기존 ai 세션이 아니라 전용 세션이다 — 자동복원과의 경쟁 회피)
• data/sessions.json이 손상되면 다음 시작 시 자동으로 data/sessions.json.bad로 옮겨지고 채널→세션 매핑은 빈 상태로 초기화된다. 특정 채널의 세션만 리셋하고 싶다면 파일 전체가 아니라 해당 채널 항목만 삭제하면 된다.