Hermes Agent

Hermes는 Chorus 공식 MCP 도구, 워크플로 스킬, 세션 훅, 읽기 전용 리뷰어를 제공합니다. 원격 실행은 Hermes 게이트웨이가 담당하며 chorus daemon을 사용하지 않습니다. 게이트웨이 하나는 저장소 하나를 담당합니다.

Chorus 0.22.0부터 사용할 수 있습니다. Hermes 호환성은 커밋 2b52acc2d에서 검증했습니다.

사전 준비

Hermes를 설치하고 hermes와 git을 PATH에서 실행할 수 있게 합니다.
에이전트 접근 설정에서 Chorus URL과 키를 준비합니다. 게이트웨이 실행과 승인에는 사람 소유자가 지정된 에이전트가 필요합니다.
대상 저장소를 정합니다. 여러 저장소에는 별도의 Hermes 프로필과 HERMES_HOME을 사용합니다.

설치 및 설정

Chorus CLI 0.22.0 이상을 설치한 다음 설정합니다.

npm install --global @chorus-aidlc/chorus@latest
cd /path/to/your/repo
chorus agents add --agents hermes --hermes-cwd /path/to/your/repo

설정 과정에서 Chorus URL과 키를 입력합니다. CLI는 v<CLI version>을 전체 커밋 SHA로 해석하고 두 패키지 모두 설치해 활성화합니다. chorus는 네이티브 훅, 스킬, 게이트웨이, 승인을 제공하고 chorus-mcp는 이식 가능한 MCP 도구를 제공합니다. 태그를 해석하지 못하면 설치를 중단하며 기본 브랜치로 바꾸지 않습니다. 두 패키지가 이미 있으면 재설치를 확인합니다. --yes 또는 TTY가 없는 실행에서는 재설치를 수락합니다.

설정 과정에서 다음 항목도 저장합니다.

$HERMES_HOME/.env(기본 ~/.hermes/.env, 모드 0600)에 CHORUS_URL, CHORUS_API_KEY, CHORUS_AGENT_PROFILE을 저장하고 다른 항목은 유지합니다.
원격 Chorus에 필요한 네이티브 mcp_servers.chorus 설정을 추가합니다. localhost로 돌아올 때도 기존 고정 네이티브 URL을 수정합니다.
$HERMES_HOME/config.yaml에 terminal.cwd와 아직 설정하지 않은 승인 옵션을 저장합니다. --hermes-cwd가 우선하며, 없으면 기존 디렉터리 또는 현재 Git 저장소를 사용합니다. 저장소 밖의 비대화형 실행에서는 경고하고 미설정 상태를 유지합니다. 기존 승인 설정은 덮어쓰지 않습니다.

Chorus daemon 설정에서 Hermes는 offline으로 등록됩니다. 이는 daemon이 깨우지 않는다는 뜻이며 실행 중인 Hermes 게이트웨이가 오프라인이라는 뜻이 아닙니다. chorus daemon --agent hermes나 chorus agents run --type hermes 대신 Hermes를 직접 실행하세요.

수동 설치

--ref에는 태그나 짧은 SHA가 아닌 40자 전체 커밋 SHA가 필요합니다. 먼저 릴리스 태그를 해석합니다. 폴백은 경량 태그도 지원합니다.

VERSION=0.22.0
REPO=https://github.com/Chorus-AIDLC/Chorus.git
SHA=$(git ls-remote "$REPO" "refs/tags/v$VERSION^{}" | cut -f1)
[ -n "$SHA" ] || SHA=$(git ls-remote "$REPO" "refs/tags/v$VERSION" | cut -f1)
[ -n "$SHA" ] || { echo "error: tag v$VERSION not found" >&2; exit 1; }
hermes plugins install Chorus-AIDLC/Chorus/packages/chorus-hermes/chorus --ref "$SHA" --enable
hermes plugins install Chorus-AIDLC/Chorus/packages/chorus-hermes/chorus-mcp --ref "$SHA" --enable
hermes plugins list --plain --no-bundled

수동 설치 후 $HERMES_HOME/.env(기본 ~/.hermes/.env)를 안전하게 편집합니다.

CHORUS_URL=https://chorus.example.com
CHORUS_API_KEY=cho_REDACTED

키를 로컬에서 바꾸고 파일 모드를 0600으로 제한하며 커밋하지 마세요. Hermes는 서비스 시작 시에도 이 파일을 읽고 오래된 셸 값보다 우선합니다. 서비스는 터미널의 export를 상속하지 않습니다. 모델 공급자 인증은 Hermes의 일반 설정을 통해 별도로 제공하세요.

MCP URL과 작업 디렉터리

이식 가능한 패키지는 http://localhost:8637/api/mcp를 사용합니다. 다른 Chorus 인스턴스에는 네이티브 설정을 사용합니다. 작은따옴표를 유지하여 비밀값 대신 자리표시자를 저장하세요.

hermes config set mcp_servers.chorus.url '${CHORUS_URL}/api/mcp'
hermes config set mcp_servers.chorus.headers.Authorization 'Bearer ${CHORUS_API_KEY}'
hermes config set terminal.cwd /path/to/your/repo

네이티브 설정이 우선하므로 이식 가능한 chorus 서버가 충돌하여 건너뛰었다는 로그는 정상입니다. 연결 대상을 바꿀 때도 MCP와 게이트웨이가 같은 인스턴스를 가리키게 하세요.

서비스 자체의 디렉터리는 저장소가 아닙니다. 각 실행은 terminal.cwd를 사용하고 실제 경로를 Chorus에 보고합니다. 미설정이거나 ., auto, cwd이면 로컬 터미널 백엔드는 MESSAGING_CWD로 폴백할 수 있습니다. 마지막 후보가 $HOME뿐이면 연결을 거부합니다. 설정 변경 후 게이트웨이를 다시 시작하세요.

Chorus에서 명령 승인

자동 설정도 기존 선택을 유지하므로 다음 설정을 확인하세요.

hermes config set security.approval.transport chorus
hermes config set security.approval.transport_fallback builtin
hermes config set approvals.mode manual
hermes config set approvals.timeout 300

manual은 표시된 명령을 사람에게 확인합니다. smart에서는 가디언 모델이 사용자에게 묻지 않고 승인할 수 있습니다. builtin은 Chorus가 시작하지 않은 CLI/TUI 세션의 대화형 승인을 유지합니다. 선택적 시간 제한은 초 단위이며 응답이 없으면 거부합니다.

에이전트는 현재 아이디어나 작업에 댓글을 달고 소유자를 멘션하며 6자 토큰을 제공합니다. 소유자가 같은 항목에 approve once <token> 또는 deny <token>으로 답해야 합니다. approve session <token>이나 approve always <token>은 해당 선택지가 제공되고 더 넓은 권한을 의도할 때만 사용합니다. 일치하는 승인 답장은 새 작업 턴을 시작하지 않습니다. 다른 사람은 명령을 승인할 수 없습니다.

답장을 고유하게 연결할 수 없으면 일반 멘션으로 처리하며 명령을 승인하지 않습니다. 거의 동시에 여러 멘션을 보내거나 턴 시각이 없는 구형 서버에서 발생할 수 있습니다. 다시 답하거나 만료를 기다리세요. 모호한 답장이 일반 작업 턴을 시작할 수 있지만 원래 승인은 미응답입니다.

시작 및 확인

hermes gateway install
hermes gateway start
hermes gateway status
hermes chat -q "call chorus_checkin"

포그라운드 진단에는 hermes gateway run, 기존 서비스 재시작에는 hermes gateway restart를 사용합니다. URL과 키가 있고 플러그인이 활성화되면 chorus 플랫폼도 자동 활성화됩니다. 명시적인 플랫폼 비활성화 설정은 유지됩니다.

mcp__chorus__chorus_checkin이 예상 신원을 반환하고 Chorus에 올바른 저장소의 온라인 Hermes 연결이 표시되는지 확인합니다. 아이디어나 작업을 할당하거나 멘션하여 대화에 출력이 도착하는지 확인하세요.

스킬, 제어, 복구

skill_view("chorus:develop") 또는 skill_view("chorus:yolo")로 스킬을 불러옵니다. 아이디어, 조사, 제안, 개발, 검토, 오케스트레이션, quick-dev, 문서, OpenSpec/spec-lite, 세 종류의 리뷰어가 포함됩니다. delegate_task 리뷰어의 context는 [chorus-reviewer:proposal], [chorus-reviewer:task], [chorus-reviewer:code] 중 하나로 시작합니다. 표시된 리뷰어는 읽기와 판정 댓글만 가능하며 터미널 실행, 파일 편집, 재위임은 할 수 없습니다.

세션 시작 시 체크인하여 신원과 명세 모드를 제공합니다. CHORUS_ENABLE_OPENSPEC=false는 OpenSpec 탐지를 끕니다(이전 설정은 CHORUS_OPENSPEC_MODE=off). CHORUS_ENABLE_CODE_REVIEWER=false는 최종 코드 검토 알림을 끕니다.

Interrupt는 실행 중인 게이트웨이 작업을 취소하고 Resume은 원래 게이트웨이와 저장소에서 계속합니다. 오프라인이면 먼저 다시 시작하세요. 복구에는 Hermes 연속 턴을 지원하는 Chorus 서버가 필요합니다. 구형 서버에서는 관련 없는 대기 지시를 실행하는 대신 거부합니다. 재연결은 서버에서 대기 작업을 복구하지만 완료한 명령을 되돌리지는 않습니다. 세션 복구도 참조하세요.

제한 및 문제 해결

조사와 아이디어 생성 전용 작업 턴은 게이트웨이가 아직 실행하지 않습니다. 해당 UI 동작에는 Claude Code/Codex daemon을 사용하거나 Hermes 대화형 세션에서 작업하세요.
계속 오프라인: 두 플러그인, 인증 및 모델 설정, 소유자, terminal.cwd를 확인합니다. chorus daemon logs가 아닌 Hermes 게이트웨이 로그를 확인하세요.
연결 충돌: 같은 에이전트, 호스트, cwd에는 연결 하나만 가능합니다. 중복을 중지하거나 다른 저장소/에이전트로 바꾸고 다시 시작합니다. 충돌 시 자동 재연결을 중지합니다.
도구 없음: chorus-mcp, 네이티브 원격 URL, 키를 확인합니다. 해석하지 못한 인증 자리표시자는 사용할 수 없습니다. 플러그인 보안 검사를 우회하지 마세요.
승인 거부: 소유자, 토큰, 항목, 시간 제한, builtin을 확인합니다. 묻지 않고 실행되었다면 smart 모드인지 확인합니다.
알림이 일찍 읽음 처리됨: 체크인은 최근 알림 최대 5개를 읽음 처리하지만 게이트웨이는 읽지 않은 알림뿐 아니라 서버의 대기 작업도 복구합니다.
업데이트: 두 플러그인을 검증한 동일한 새 SHA로 설치하고 게이트웨이를 다시 시작합니다. chorus upgrade --plugins는 Hermes의 offline 등록을 업데이트하지 않습니다. CLI 업데이트 후 chorus agents add --agents hermes로 두 패키지를 다시 설치할 수 있습니다.

권한이나 키 문제는 연결 문제 해결을 참조하세요.