55분 분량

Hermes Agent 입문

읽은 깊이
시작 전

Hermes Agent 입문

작성일: 2026-10-07
기준 자료: Hermes Agent 공식 문서(GitHub NousResearch/hermes-agent의 website/docs/, 커밋 a50406d, 2026-10-07). 같은 날 이 맥에 설치된 버전(Hermes Agent v0.21.5, upstream a50406d9)과 같은 커밋이다. Hermes는 업데이트가 매우 잦으므로, 몇 달 뒤 읽는다면 명령어와 기본값을 문서에서 다시 확인한다.

목표: Claude Code와 Codex를 이미 매일 쓰는 사람이 “Hermes에서는 이걸 어떻게 하지?”를 바로 찾을 수 있게 하기. 특히 SOUL.md가 CLAUDE.md와 어떻게 다르게 돌아가는지, 여러 에이전트를 어떻게 편하게 굴리는지, 대시보드에서 무엇을 볼 수 있는지, 프로젝트 기능이 있는지를 정리한다.

Git worktree가 낯설면 Git 입문을, 컨테이너 샌드박스가 낯설면 Docker 입문을 먼저 읽는 편이 좋다.

한 줄로 먼저

Hermes Agent는 Nous Research가 만든 오픈소스 개인 에이전트다. 터미널 코딩 에이전트(Claude Code·Codex와 같은 계열)에 “항상 켜져 있는 비서” 기능을 붙인 것이라고 보면 된다.

Claude Code와 가장 크게 다른 점은 세 가지다.

  1. 상주한다. hermes gateway라는 백그라운드 프로세스가 계속 돌면서 Telegram·Slack 메시지를 받고, cron 작업을 실행하고, kanban 카드를 일꾼 에이전트에게 나눠 준다.
  2. 스스로 배운다. 대화 중에 알게 된 사실을 MEMORY.md·USER.md에 직접 적고, 반복되는 작업 절차를 skill로 직접 만든다. 공식 문서는 이것을 “built-in learning loop”라고 부른다.
  3. 모델에 묶여 있지 않다. Anthropic, OpenAI Codex(ChatGPT 구독), OpenRouter, Nous Portal, 로컬 모델 등을 hermes model로 고른다.
                 ┌────────── 사람이 들어오는 문 ──────────┐
  터미널(hermes, hermes --tui)   Desktop 앱   웹 대시보드   Telegram/Slack/...
                 └──────────────┬──────────────────────────┘
                                ▼
                     Hermes 에이전트 (profile 단위)
            SOUL.md · MEMORY.md · USER.md · skills · config.yaml
                                │
          ┌─────────────┬───────┴───────┬──────────────┐
          ▼             ▼               ▼              ▼
     delegate_task    cron 작업     kanban 일꾼     /loop·/goal
     (세션 안 하위    (매번 새 세션)  (profile별 OS   (지금 세션 안에서
      에이전트)                       프로세스)        반복)

0. 파일 지도: ~/.hermes 안에 무엇이 있나

Hermes의 모든 상태는 기본적으로 ~/.hermes/ 아래에 있다. Claude Code의 ~/.claude/에 해당한다.

경로역할Claude Code에서 비슷한 것
~/.hermes/config.yaml모든 설정~/.claude/settings.json
~/.hermes/.envAPI 키, 봇 토큰환경 변수
~/.hermes/SOUL.md에이전트 정체성(말투·성격)output style + 전역 CLAUDE.md의 말투 부분
~/.hermes/memories/MEMORY.md, USER.md에이전트가 직접 쓰는 기억auto-memory MEMORY.md
~/.hermes/skills/skill 모음~/.claude/skills/
~/.hermes/state.db모든 세션 기록(SQLite, 전문 검색 가능)~/.claude/projects/*.jsonl
~/.hermes/cron/jobs.json예약 작업(Claude Code는 세션 안 cron만 있음)
~/.hermes/kanban.dbkanban 보드없음
~/.hermes/profiles/<이름>/다른 profile의 홈 전체없음(가장 가까운 것은 별도 config dir)

profile을 만들면 위 구조 전체가 ~/.hermes/profiles/<이름>/ 아래에 한 벌 더 생긴다. 출처: user-guide/which-file-does-what.md, user-guide/profiles.md.

1. 설치와 첫 실행

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash   # macOS/Linux/WSL2
hermes setup          # 대화형 설정 마법사
hermes model          # 모델·제공자 고르기
hermes                # 클래식 CLI
hermes --tui          # 새 TUI (문서가 "recommended"라고 표시)
hermes desktop        # Desktop 앱 (macOS는 Apple Silicon만 지원)
hermes doctor         # 문제 진단
  • 코드는 ~/.hermes/hermes-agent/, 실행 파일은 ~/.local/bin/hermes, 데이터는 ~/.hermes/에 들어간다.
  • Anthropic은 API 키 또는 “Max plan + extra usage credits(OAuth)“로 붙는다. OpenAI Codex는 ChatGPT·Codex 구독으로 hermes model에서 device code 인증을 한다.
  • Claude Code·Codex 로그인을 빌려 쓴다. Hermes는 ~/.codex/auth.json과 Claude Code 자격 증명을 가져다 쓸 수 있다(auth.adopt_external_logins, 기본 true). refresh token이 한 번 쓰면 바뀌는 방식이라 원래 CLI와 충돌할 수 있다. 충돌이 보이면 auth.adopt_external_logins: false로 끈다.

출처: getting-started/installation.md, getting-started/quickstart.md, user-guide/security.md.

2. SOUL.md와 CLAUDE.md는 어떻게 다르게 돌아가나

2-1. 결론부터

  • SOUL.md는 “누구인가”(말투·성격·태도), AGENTS.md·CLAUDE.md는 “이 저장소에서 어떻게 일하나”(규칙·경로·명령어) 를 담는다. 공식 가이드도 저장소 규칙·경로·포트 같은 것은 SOUL.md가 아니라 AGENTS.md에 넣으라고 한다.
  • SOUL.md는 전역 하나(profile마다 하나) 뿐이다. 프로젝트 폴더에 SOUL.md를 두어도 읽지 않는다.
  • 프로젝트 파일은 한 종류만 읽는다. AGENTS.md가 있으면 CLAUDE.md는 무시된다. Claude Code처럼 여러 파일이 합쳐지지 않는다.

2-2. 시스템 프롬프트 조립 순서

Hermes는 시스템 프롬프트를 세 층으로 쌓고, 통째로 캐시한다. 그래서 어느 파일을 고쳐도 새 세션부터 반영된다.

[stable 층]   1. 정체성: SOUL.md (없거나 비어 있으면 내장 기본 문구)
              2. 도구·모델 안내, 코딩 작업 지침, 플랫폼 힌트
[context 층]  3. 프로젝트 파일 (.hermes.md / AGENTS.md / CLAUDE.md / .cursorrules 중 하나)
              4. git 작업 공간 스냅샷
[volatile 층] 5. skill 목록(index)
              6. MEMORY.md 스냅샷, USER.md 스냅샷
              7. 외부 메모리 제공자 블록(Honcho 등, 켰을 때만)
              8. 시각·세션·모델·cwd 줄

출처: developer-guide/prompt-assembly.md. 같은 문서 안의 예시와 personality.md는 이 순서를 조금 다르게 그린다. 위의 층 구분이 가장 자세한 설명이다.

2-3. SOUL.md

  • 위치: ~/.hermes/SOUL.md(profile을 쓰면 ~/.hermes/profiles/<이름>/SOUL.md). 작업 폴더는 절대 찾아보지 않는다.
  • 시스템 프롬프트의 1번 자리에 들어가며, 내장 정체성 문구(“You are Hermes Agent, built by Nous Research…“)를 통째로 대체한다. 감싸는 문구도 붙지 않는다.
  • 파일이 없으면 Hermes가 기본 SOUL.md를 한 번 만들어 주고, 이미 있으면 절대 덮어쓰지 않는다.
  • 길이 제한: context_file_max_chars를 따로 정하지 않으면 모델의 컨텍스트 크기에 비례해 정해진다(최소 20,000자, 최대 500,000자). 넘치면 앞 70%와 뒤 20%만 남기고 가운데를 자른다.
  • 보안 검사: 내가 쓴 SOUL.md에서 프롬프트 주입 같은 패턴이 걸리면 경고만 하고 그대로 읽는다. 프로젝트 파일(AGENTS.md 등)에서 걸리면 [BLOCKED: ...]로 막는다.
  • 하위 에이전트(delegate_task)는 SOUL.md를 받지 않고 내장 정체성으로 시작한다.

출처: user-guide/features/personality.md, user-guide/features/context-files.md, guides/use-soul-with-hermes.md.

2-4. 프로젝트 파일 우선순위

한 세션에 첫 번째로 찾은 한 종류만 읽는다.

.hermes.md (또는 HERMES.md)  >  AGENTS.override.md  >  AGENTS.md  >  CLAUDE.md  >  .cursorrules
  • .hermes.md: Hermes 전용, 가장 높은 우선순위. cwd에서 git 루트까지 위로 올라가며 찾는다.
  • AGENTS.override.md: 같은 폴더의 AGENTS.md를 대신 읽는다. git에 올리지 않는 개인용 덮어쓰기 용도다.
  • git 저장소 안이면 git 루트부터 cwd까지 AGENTS.md를 사슬로 이어 읽는다(깊은 쪽이 나중에 와서 우선). git 밖이면 cwd만 본다.
  • 작업 중에 도구가 하위 폴더를 건드리면, 그 폴더의 AGENTS.md·CLAUDE.md를 찾아 도구 결과 뒤에 붙인다(파일당 32,000자 제한). 시스템 프롬프트 캐시를 깨지 않으려는 설계다.
  • 사용자 전역 CLAUDE.md(~/.claude/CLAUDE.md)에 해당하는 “전역 규칙 파일”은 문서에 없다.

이 vault에 적용하면: vault 루트에는 AGENTS.md와 CLAUDE.md가 둘 다 있다. 따라서 Hermes는 AGENTS.md만 읽고 CLAUDE.md는 읽지 않는다. vault는 git 저장소가 아니므로 cwd의 파일만 본다. 또 파일 하나를 읽는 데 context_file_read_timeout(기본 5초)보다 오래 걸리면 경고와 함께 건너뛴다. 문서가 iCloud Drive를 그 예로 직접 든다. CLAUDE.md에만 있는 규칙(교양 노트 Reading-Status, paper 13키 계약 등)을 Hermes도 지키게 하려면 그 내용을 AGENTS.md에도 넣거나 .hermes.md를 따로 만들어야 한다.

2-5. 메모리: Claude Code auto-memory와 비교

HermesClaude Code auto-memory
파일~/.hermes/memories/MEMORY.md(에이전트 메모, 2,200자) + USER.md(사용자 프로필, 1,375자)프로젝트별 memory/ 디렉터리 + MEMORY.md 색인
범위profile 단위(프로젝트 단위 아님)프로젝트 단위
크기합쳐서 약 3,575자로 딱 잘려 있음파일 여러 개
쓰는 방법memory 도구(add/replace/remove)Write 도구
반영 시점세션 시작 때 한 번 찍은 고정 스냅샷. 세션 중에 쓴 내용은 다음 세션부터 보임세션 시작 때 색인 로드
가득 차면도구가 에러를 내고 에이전트가 직접 정리. 자동 압축 없음—
  • 약 10턴마다 배경에서 “self-improvement review”가 돌며 메모리나 skill을 저장할 수 있다. 저장하면 Memory updated 알림이 뜬다(display.memory_notifications).
  • 모델이 마음대로 저장하는 게 싫으면 memory.write_approval: true로 승인제로 바꾼다. /memory pending, /memory approve <id|all>로 처리한다.
  • 지난 대화는 메모리와 별개로 session_search 도구가 state.db를 전문 검색한다.
  • Honcho, Mem0, Hindsight 같은 외부 메모리 제공자를 하나만 더 붙일 수 있다(hermes memory setup). 내장 메모리는 계속 돈다.

출처: user-guide/features/memory.md, user-guide/features/memory-providers.md, user-guide/features/curator.md.

2-6. Claude Code 개념 대응표

Claude CodeHermes메모
프로젝트 CLAUDE.mdAGENTS.md·.hermes.md (CLAUDE.md는 둘 다 없을 때만)한 종류만 읽음
하위 폴더 CLAUDE.md하위 폴더 AGENTS.md·CLAUDE.md 점진 발견도구 결과에 붙음
~/.claude/CLAUDE.md말투는 SOUL.md, 사실은 MEMORY.md·USER.md가져오기 하면 메모리 항목이 됨
CLAUDE.local.mdAGENTS.override.md가 가장 가까움문서가 같다고 말하진 않음
output style없음. SOUL.md + /personality 조합3절 참고
auto-memoryMEMORY.md + USER.md크기 고정, profile 단위
--resumehermes -c, hermes --resume, session_search10절 참고
~/.claude/skills/~/.hermes/skills/agentskills.io 형식
커스텀 slash commandskill로 변환가져오기에서 건너뜀
hooksshell hooks(hooks: in config.yaml)exit code 2로 차단, Claude Code와 호환
subagentdelegate_task8절 참고
설정 묶음 여러 개profile8절 참고
@file@file:, @folder:, @diff, @staged, @git:N, @url:문법이 다름
자동 compactcompression.* (기본: 컨텍스트 50%에서)요약 모델 따로 지정 가능

3. output style에 해당하는 것은?

Hermes에는 “output style”이라는 기능이 없다. 문서 전체에서 그런 기능 페이지를 찾을 수 없다. 대신 아래를 조합한다.

  1. SOUL.md: 늘 적용되는 기본 말투·성격. 가장 가까운 대응물이다. 다만 Claude Code output style처럼 “코딩 지침은 그대로 두고 말투 층만 바꾸는” 구조가 아니라, 정체성 블록 전체를 대체한다.
  2. /personality <이름>: 세션 단위로 SOUL.md 위에 덧씌우는 프리셋.
    • 내장 14종: helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype.
    • 직접 만들기: config.yaml의 agent.personalities.<이름>: "프롬프트 문장". 내장 이름을 다시 쓰면 덮어쓴다.
    • 해제: /personality none.
    • 메신저 채팅 안에서도 된다.
  3. platform_hints.<플랫폼>: 터미널·Telegram 등 화면별 서식 힌트(예: “터미널이니 Markdown 쓰지 마라”). append/replace를 고를 수 있다.
  4. agent.reasoning_effort(none부터 ultra까지)와 /reasoning show|hide: 생각 깊이와 표시 여부.
  5. agent.text_verbosity: 답변 길이. OpenAI Responses API 모델에서만 동작한다.
  6. skin(/skin, display.skin): CLI의 겉모양만 바꾼다(배너 색, 스피너, 라벨). 모델 행동에는 영향이 없다고 문서가 명시한다.

지금 쓰는 Claude Code output style(결론 먼저, 짧은 문장, 한국어)을 Hermes로 옮기려면, 그 본문을 ~/.hermes/SOUL.md에 넣는 것이 가장 가깝다. 메신저용 말투를 따로 두고 싶으면 agent.personalities에 하나 더 만들어 /personality로 바꾼다.

출처: user-guide/features/personality.md, user-guide/features/skins.md, user-guide/configuration.md, developer-guide/prompt-assembly.md.

4. Skills: Claude Code skill을 그대로 쓸 수 있나

  • 형식은 agentskills.io 표준이다. 폴더 하나에 SKILL.md(필수)와 references/, templates/, scripts/ 등을 둔다. Claude Code skill과 구조가 같다.
  • 찾는 위치(우선순위 순): 프로젝트의 .hermes/skills/·.agents/skills/(처음 한 번 hermes skills trust 필요), ~/.hermes/skills/, skills.external_dirs에 적은 폴더.
  • 설치된 skill은 전부 /skill이름으로 부를 수 있고, 한 메시지에 최대 5개까지 이어 붙일 수 있다.
  • 에이전트가 skill_manage 도구로 skill을 스스로 만들고 고친다. /learn <출처>로 폴더·URL·지금 대화에서 skill을 만들 수도 있다. 모델이 마음대로 쓰는 게 싫으면 skills.write_approval을 켠다.
  • curator: 에이전트가 만든 skill 중 14일 안 쓴 것은 stale, 30일이면 ~/.hermes/skills/.archive/로 보낸다. 절대 지우지 않는다. 내가 직접 쓴 skill은 건드리지 않는다.
  • Claude Code skill 재사용: ~/.claude/skills를 직접 읽는다는 설명은 문서에 없다. 문서에 있는 길은 두 가지다.
    • hermes import-agent claude-code: ~/.claude/skills/<이름>/을 ~/.hermes/skills/claude-code-imports/<이름>/으로 복사한다.
    • skills.external_dirs에 폴더를 추가한다. 문서 예시는 ~/.agents/skills뿐이라, Claude 전용 도구 이름을 쓰는 skill이 잘 도는지는 직접 확인해야 한다.

hermes import-agent claude-code로 넘어가는 것

hermes import-agent claude-code --dry-run   # 먼저 미리보기
hermes import-agent claude-code
hermes import-agent --sync                  # 바뀐 것만 다시 가져오기 (cron에 걸어도 안전)
  • 전역 CLAUDE.md → 메모리 항목(MEMORY.md)이 된다. 2,200자 제한에 걸리므로 긴 CLAUDE.md는 손으로 AGENTS.md·.hermes.md로 옮기는 편이 낫다. 긴 파일을 어떻게 처리하는지는 문서에 없다.
  • permissions.allow의 Bash(...) 규칙 → command_allowlist, permissions.deny → approvals.deny.
  • mcpServers → config.yaml의 mcp_servers.
  • skills/ → claude-code-imports/.
  • 건너뛰는 것: commands/*.md(slash command), Bash(...)가 아닌 권한 규칙. API 키·자격 증명은 절대 가져오지 않는다.
  • hooks, subagent 정의, output style, ~/.claude/projects/의 auto-memory를 가져온다는 말은 문서에 없다.

출처: user-guide/features/skills.md, user-guide/features/curator.md, user-guide/import-from-other-agents.md.

5. Bot mode와 메시징 gateway

이름이 비슷하지만 서로 다른 기능 두 개다.

5-1. Bot mode (Desktop 앱 기능)

  • profile 하나 = Bot 하나다. 새로운 개념이 아니라 profile을 이름·역할·아바타가 있는 “동료”처럼 보여 주는 UI다.
  • Desktop 앱에 내장돼 있고 기본으로 켜져 있다. 왼쪽 사이드바의 Bots 탭에서 보인다. 끄려면 Capabilities → Plugins → Bots.
  • 핵심 개념:
    • Bot Chat: Bot마다 하나 있는 영구 대화. 이 안에서 /new·/reset을 치면 /compact로 바뀐다.
    • Routines: Bot에 붙은 반복 작업. 실체는 [bot:<이름>] ... 이름의 평범한 cron 작업이다.
    • 그룹 채팅: Bot 2–6개가 한 방에서 토론한다. 메시지 하나에 최대 3라운드, 10개 메시지까지. Bot이 @user로 나를 부르면 “needs you” 표시가 뜬다.
    • Bot끼리 메시지: 아무 채팅에서 @researcher 이거 봐 줘라고 하면 그 Bot이 message_agent 도구로 자기 말로 전달한다. 받는 Bot은 다음에 실행될 때 읽는다.
  • 터미널과 1:1로 대응한다.
hermes -p <bot> chat          # 그 Bot과 대화
ls ~/.hermes/profiles/<bot>/  # 그 Bot의 파일·skill·메모리
hermes cron list              # Routines 보기
  • 로컬 Bot은 각자 백엔드 프로세스를 띄운다. 동시에 살려 두는 수는 Settings → Advanced → Warm Bot Backends(기본 3개, 각 약 60MB)다.
  • Desktop 없이 터미널만 쓰면 message_agent가 나타나지 않는다. 손으로 hermes -p <bot> chat -c "Bot Chat" --create-if-missing을 하고, profile의 profile.yaml에 ui_meta: { hermes-bots: {} }를 넣어야 한다.
  • Bot Screen(Bot마다 가상 데스크톱)은 Linux gateway 호스트 전용이다. macOS에서는 제공되지 않는다.

출처: user-guide/bot-mode.md, user-guide/features/bot-screen.md.

5-2. 메시징 gateway (휴대폰에서 에이전트 부르기)

  • hermes gateway는 하나의 백그라운드 프로세스로, 설정한 모든 메신저에 연결하고, 세션을 관리하고, cron과 kanban 디스패처도 함께 돌린다.
  • 지원: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Matrix, Mattermost, Microsoft Teams, Google Chat, LINE, iMessage(BlueBubbles·Photon), IRC 등 약 30개, 그리고 Webhook과 OpenAI 호환 API 서버.
hermes gateway setup      # 대화형 마법사
hermes gateway            # 앞에서 실행
hermes gateway install    # macOS: launchd 등록 (~/Library/LaunchAgents/ai.hermes.gateway.plist)
hermes gateway start | stop | status | restart
tail -f ~/.hermes/logs/gateway.log

Telegram 최소 설정

  1. Telegram에서 @BotFather에게 /newbot을 보내고 토큰을 복사한다.
  2. @userinfobot에서 내 숫자 user ID를 확인한다(username이 아니다).
  3. ~/.hermes/.env에 넣는다. 
    TELEGRAM_BOT_TOKEN=123456789:ABC...
TELEGRAM_ALLOWED_USERS=123456789
  4. hermes gateway를 실행하고, 봇과의 채팅에서 /sethome을 쳐서 cron 결과가 올 “홈 채널”로 정한다.

대시보드·Desktop의 Messaging → Telegram에 있는 Create with QR을 쓰면 위 과정을 자동으로 해 준다.

보안 모델

  • 기본은 전원 거부다. allowlist(TELEGRAM_ALLOWED_USERS 등)에 있거나 DM pairing(hermes pairing approve telegram <코드>)을 거친 사람만 쓸 수 있다.
  • GATEWAY_ALLOW_ALL_USERS=true는 에이전트가 터미널을 쓸 수 있으므로 문서가 권하지 않는다.
  • 위험한 명령은 승인을 받는다. approvals.mode가 smart(기본: 보조 LLM이 위험도 판단), manual(항상 묻기), off(= --yolo) 중 하나다. 채팅에서는 yes/no나 /approve·/deny로 답한다. 300초 안에 답이 없으면 거부로 처리한다.
  • rm -rf / 같은 하드라인 차단 목록과 내가 적은 approvals.deny(예: "git push --force*")는 yolo에서도 막힌다.
  • Docker·Modal 같은 컨테이너 터미널 백엔드에서는 승인 검사를 건너뛴다. 컨테이너가 경계라고 보기 때문이다.

채팅 안 세션

  • 메신저 대화는 시간이 지나도 저절로 초기화되지 않는다. /new나 /reset을 쳐야 새 대화가 된다.
  • 그룹에서는 기본적으로 사람마다 세션이 따로다(group_sessions_per_user: true).
  • 유용한 채팅 명령: /model, /personality, /stop, /usage, /compress, /title, /resume, /sessions search <검색어>, /bg <프롬프트>(별도 세션에서 돌리고 결과만 이 채팅으로), /btw <질문>, /rollback, /<skill이름>.
  • 채널마다 모델·시스템 프롬프트를 바꿀 수 있다: platforms.<이름>.channel_overrides.<채널ID>.
  • 음성 메시지는 자동으로 받아 적는다(로컬 faster-whisper는 키 없이 동작).

출처: user-guide/messaging/index.md, user-guide/messaging/telegram.md, user-guide/messaging/slack.md, user-guide/security.md, user-guide/sessions.md.

6. 자동화 네 가지: cron, /loop, /goal, /heartbeat

언제 돌아가나어디서끝나는 조건쓰는 곳
cron일정에 맞춰매번 새 세션내가 지울 때사람 없이 정기적으로
/loop타이머(또는 스스로 간격 조절)지금 세션멈춤 조건·횟수·내가 멈출 때작업 중 상태 확인(폴링)
/goal매 턴 뒤 판정 모델이 “아직”이라고 할 때지금 세션목표 달성·턴 예산·내가 멈출 때”X가 될 때까지 계속”
/heartbeat세션이 한가하고 간격이 지났을 때지금 세션(맥락 유지)clear할 때메신저 대화 안 주기적 점검

6-1. cron

  • gateway가 돌고 있어야 실행된다. gateway가 60초마다 확인해서, 때가 된 작업마다 새 에이전트 세션을 띄운다. 그냥 CLI 대화를 열어 둔 것으로는 실행되지 않는다. Desktop 앱은 자체 타이머가 있어서 gateway 없이도 로컬 profile의 cron을 돌린다.
  • 맥이 꺼져 있던 동안 놓친 반복 작업은 켜진 뒤 한 번만 따라잡는다(cron.catch_up_missed).
# 만들기 (셋 다 같은 결과)
/cron add "every 2h" "Check server status"            # 채팅에서
hermes cron create "every 2h" "Check server status"   # 터미널에서
"매일 아침 9시에 HN AI 뉴스 요약해서 Telegram으로 보내 줘"   # 그냥 말로
 
# 관리
hermes cron list | status | runs <id> | doctor
hermes cron pause|resume|run|remove <id 또는 이름>
hermes cron edit <id> --schedule "every 4h" --skill arxiv
hermes pause / hermes resume      # 전체 비상 정지
  • 일정 형식: in 30m(한 번), every 2h(간격), weekdays at 9am(자연어), 0 9 * * 1-5(cron 식). 자연어 일정은 cron.md에는 지원한다고 나오고 automate-with-cron.md에는 지원하지 않는다고 나온다. cron 식이 가장 안전하다.
  • 결과 전달: --deliver telegram, telegram:<chat_id>, slack, discord:#채널, local(파일로만 저장), all 등. 에이전트의 마지막 답이 자동으로 전달된다.
  • 답 전체가 [SILENT]이면 전달하지 않는다. “새 논문 없으면 [SILENT]만 답해” 같은 프롬프트에 쓴다.
  • 작업 옵션:
    • --skill <이름>: skill을 붙인다.
    • --workdir <절대경로>: 그 폴더의 AGENTS.md·CLAUDE.md를 읽고 그 폴더에서 작업한다.
    • --model, --provider, --pin: 작업마다 모델을 고정한다. 고정한 작업은 fallback 제공자로 넘어가지 않고 실패한다.
    • --reasoning-effort: 작업마다 생각 깊이.
    • --continuity: 지난번 결과를 넣어 줘서 중복을 피하게 한다.
    • context_from: 다른 작업의 최근 결과를 앞에 붙여 “수집 → 선별 → 전달” 파이프라인을 만든다.
  • 토큰을 안 쓰는 방법 두 가지:
    • --no-agent --script <파일>: LLM 없이 스크립트만 돌리고 stdout을 그대로 보낸다. 출력이 비면 조용히 넘어간다.
    • --script <파일>(agent 모드): 스크립트 출력의 마지막 줄이 {"wakeAgent": false}이면 그 회차는 LLM을 부르지 않는다.
    • 스크립트는 반드시 ~/.hermes/scripts/ 안에 있어야 한다. Hermes 자체 Python에는 내 패키지가 없으므로 --interpreter ~/venvs/x/bin/python으로 내 가상환경을 지정한다.
  • 프롬프트는 혼자서 이해되게 써야 한다. 매번 새 세션이라 이전 대화를 모른다.

출처: user-guide/features/cron.md, guides/automate-with-cron.md, guides/cron-script-only.md, guides/cron-troubleshooting.md.

6-2. /loop, /goal, /heartbeat

/loop 5m 학습 로그 확인하고 끝났으면 LOOP_COMPLETE라고 답해 --times 60
/loop status | pause | resume | stop
 
/goal tests/ 아래 실패하는 테스트를 모두 고쳐라
/goal gate add scripts/run_tests.sh     # 이 명령이 exit 0이어야 판정 모델에게 넘어감
/goal status | pause | resume | clear
 
/heartbeat every 10m 배포 상태 확인하고 의미 있는 변화만 보고해
/heartbeat status | pause | resume | clear
  • /loop는 Claude Code의 /loop와 같은 개념이다. 간격을 빼면 1분에서 시작해 답이 안 바뀌면 15분까지 늘린다. 세션당 하나, 기본 최대 100회(loops.max_ticks).
  • /goal은 “Ralph loop”, Codex CLI의 /goal과 같은 개념이다. 판정 모델이 매 턴 done/continue/blocked/wait를 판단한다. 기본 예산은 20턴(goals.max_turns). 판정은 auxiliary.goal_judge로 싼 모델에 맡길 수 있다. 판정 모델이 에러를 내면 “continue”로 처리하므로 턴 예산이 마지막 안전장치다.
  • 셋 다 매 회차가 진짜 에이전트 턴이라 간격만큼 비용이 든다.

출처: user-guide/features/loops.md, user-guide/features/goals.md, user-guide/features/heartbeat.md.

6-3. hooks와 webhook

  • shell hooks는 Claude Code hooks와 거의 같다. config.yaml의 hooks: 아래에 pre_tool_call 등을 적고, 스크립트가 exit code 2를 내면 도구 호출을 막는다(Claude Code·Cursor 호환). 처음 쓸 때 승인을 묻고 ~/.hermes/shell-hooks-allowlist.json에 기록한다. gateway·cron처럼 터미널이 없는 실행에서는 hooks_auto_accept: true 등을 켜지 않으면 새 hook이 조용히 등록되지 않는다.
  • webhook: POST http://host:8644/webhooks/<route>로 GitHub 이벤트 등을 받아 에이전트를 돌린다. hermes webhook subscribe ...로 추가한다. 공개 URL로 열면 payload를 통한 프롬프트 주입 위험이 있다.

출처: user-guide/features/hooks.md, user-guide/messaging/webhooks.md.

7. Kanban: 여러 에이전트에게 일을 나눠 맡기는 보드

7-1. 무엇인가

Kanban은 모든 profile이 함께 쓰는 작업 보드다. 카드 하나가 작업 하나이고, 카드를 맡은 profile이 별도 OS 프로세스로 떠서 그 일을 한다. 문서는 이것을 “깨지기 쉬운 세션 안 subagent 무리”의 대안이라고 소개한다.

  • 저장: ~/.hermes/kanban.db(SQLite). 보드를 더 만들면 ~/.hermes/kanban/boards/<slug>/kanban.db.
  • 카드 상태: triage → todo → ready → running → (review) → done, 그리고 blocked, archived.
  • 카드 담당자(assignee)는 profile 이름이다. 디스패처가 hermes -p <담당자> chat -q <프롬프트>를 띄우므로, 일꾼은 그 profile의 모델·SOUL.md·skill·메모리·.env를 그대로 쓴다.
  • 디스패처는 gateway 안에서 60초마다 돈다. gateway가 꺼져 있으면 ready 카드가 그냥 쌓여 있다.
  • 부모-자식 연결(link): 부모가 모두 done이 되면 자식이 ready로 올라간다. 자식은 부모의 결과 요약을 보고 시작한다.
  • 일꾼은 셸 명령이 아니라 kanban_* 도구로 보드를 다룬다: kanban_show, kanban_heartbeat, kanban_complete, kanban_block, kanban_request_review, kanban_comment 등. 이 사용법은 시스템 프롬프트에 자동으로 들어가므로 따로 설치할 것이 없다.
  • 단일 호스트 전용이다. 두 컴퓨터가 보드 하나를 공유하는 것은 지원하지 않는다.

7-2. 사람이 끼어드는 방법

  • triage: 대충 적은 아이디어를 넣는 칸. 기본 설정(kanban.auto_decompose: true)이면 디스패처가 profile 설명을 읽고 자동으로 쪼개서 적임자에게 자식 카드를 나눠 준다. 그래서 profile 설명을 잘 써 두는 것이 중요하다(hermes profile create --description "...").
  • 일꾼이 막히면 kanban_block으로 멈추고 사람을 부른다. 사람은 댓글을 달고 풀어 준다. 
    hermes kanban comment <id> "2026 스키마를 써라"
hermes kanban unblock <id>
  • 리뷰: 일꾼이 kanban_request_review를 부르면 카드가 review로 가고, 리뷰어 profile이 sdlc-review skill로 검토한다. kanban.review_dispatch: false로 두면 사람만 리뷰한다.
  • 휴대폰에서: 메신저에서 /kanban create ...로 카드를 만들면 그 채팅이 알림을 받는다. /kanban unblock t_abcd는 에이전트가 다른 일을 하는 중에도 바로 먹힌다.
  • --goal 카드: 카드 본문을 완료 기준으로 삼아 판정 모델이 확인하며 끝까지 밀어붙인다.

7-3. 자주 쓰는 명령

hermes kanban init
hermes gateway start                     # 디스패처가 여기서 돈다
hermes kanban create "논문 X의 Table 2 재현" --triage
hermes kanban create "flaky eval 고치기" --assignee coder \
    --workspace worktree --branch wt/fix-eval --max-runtime 2h --max-retries 2
hermes kanban create "수정 리뷰" --assignee reviewer --parent <id>
hermes kanban list | show <id> | watch | stats | runs <id> | tail <id>
hermes kanban context <id>               # 일꾼이 실제로 보는 내용
hermes kanban set-model <id> <model>     # 카드별 모델 바꾸기
hermes kanban swarm "<목표>" --workers researcher,architect --verifier reviewer --synthesizer writer
hermes kanban boards create thesis --name "Thesis" --switch   # 프로젝트별 보드
  • 작업 공간: scratch(기본, 끝나면 삭제), dir:<절대경로>(기존 폴더, 보존), worktree(git worktree, 보존). 남겨야 할 결과는 worktree나 dir:을 쓴다.
  • 동시 실행 제한: kanban.max_in_progress(전체), kanban.max_in_progress_per_profile(profile별).
  • 같은 오류로 2번 연속 실패하면 카드를 자동으로 막는다.

출처: user-guide/features/kanban.md, user-guide/features/kanban-tutorial.md, user-guide/features/kanban-worker-lanes.md, user-guide/features/kanban-multi-gateway.md.

8. 여러 에이전트를 편하게 쓰는 법

Hermes에서 “여러 에이전트”는 네 층으로 나뉜다. 상황에 맞는 층을 고르는 것이 핵심이다.

층무엇오래 가나사람 개입언제
delegate_task세션 안에서 하위 에이전트를 띄움아니오(/stop·재시작 시 사라짐)안 됨짧은 병렬 조사, 새 눈으로 리뷰
profile역할별로 완전히 분리된 에이전트예됨연구용·코딩용·메신저용 분리
kanbanprofile들에게 카드를 배분하는 큐예(DB에 기록)됨여러 시간짜리, 여러 단계, 재시도 필요
Bot mode 그룹profile 여러 개가 한 방에서 토론예됨의견 비교, 브레인스토밍

8-1. profile

  • profile은 완전히 별개의 Hermes 홈이다. config.yaml, .env, SOUL.md, 메모리, 세션, skill, cron이 모두 따로다. 그래서 profile마다 모델과 말투를 다르게 줄 수 있다.
hermes profile create researcher --description "논문과 문서를 읽고 결과를 정리한다."
hermes profile create coder --clone        # 현재 설정·SOUL·skill·메모리 복사
hermes profile list | use <이름> | show <이름> | delete <이름>
researcher chat                            # = hermes -p researcher chat (별칭 자동 생성)
  • 주의: profile은 샌드박스가 아니다. 파일 접근을 막지 않는다. 또 HOME을 바꾸지 않으므로 Claude Code·Codex·gh 로그인을 모든 profile이 공유한다. profile마다 따로 쓰려면 terminal.home_mode: profile.
  • 한 profile을 두 에이전트가 동시에 쓰면 안 된다. 서로의 메모리 쓰기가 섞인다.
  • gateway는 호스트 하나가 모든 profile을 맡는 방식(multiplex)이 기본이다.

8-2. delegate_task (subagent)

  • 기본 동시 10개(delegation.max_concurrent_children). Features Overview 페이지에는 아직 “3개”라고 남아 있지만, 상세 문서와 설정 예시는 10이다.
  • 자식은 빈 대화에서 시작하고, 넘겨준 goal과 context, 그리고 프로젝트 파일(AGENTS.md 등)만 본다. 최종 요약만 부모에게 돌아온다.
  • 모델은 전역 하나만 지정한다(delegation.model). 작업마다 모델을 바꾸려면 kanban 카드의 --model을 쓴다.
  • 자식은 memory, clarify(사용자에게 질문), delegate_task를 못 쓴다. 기본 깊이는 1단계(delegation.max_spawn_depth: 1).
  • delegation.worktree_isolation: true면 자식마다 git worktree를 따로 준다.
  • TUI의 /agents(또는 Ctrl+T)에서 자식 트리와 비용을 보고, x로 하나를, X로 그 아래 전체를 멈춘다.

8-3. Claude Code·Codex를 Hermes에서 부리기

  • kanban 일꾼으로 바로 등록하는 기능은 아직 없다. worker lanes 문서는 Claude Code·Codex CLI lane이 “not yet a paved path”라고 적는다.
  • 대신 기본 포함된 claude-code, codex skill로 Hermes가 터미널에서 직접 부린다.
    • Claude Code: claude -p '...' --allowedTools 'Read,Edit' --max-turns 10(print 모드), 또는 tmux 안의 대화형 TUI. 병렬이면 작업마다 tmux 세션 하나.
    • Codex: codex exec '<작업>'(git 저장소 필요, --sandbox workspace-write). 병렬이면 git worktree를 여러 개 만들고 각각 백그라운드로 실행.
    • gateway(서비스)에서 돌릴 때 Codex workspace-write 샌드박스가 bubblewrap 에러로 실패할 수 있다고 skill 문서가 경고한다.
  • Codex app-server runtime(/codex-runtime codex_app_server)은 다른 개념이다. Codex를 일꾼으로 쓰는 게 아니라, OpenAI 모델의 턴 실행 자체를 Codex 런타임에 맡긴다. ChatGPT 구독 인증과 Codex 샌드박스를 쓰는 대신 delegate_task, memory, session_search, todo가 빠진다. 베타다.
  • Mixture of Agents(/moa)는 여러 모델이 한 에이전트에게 조언하는 방식이다. 여러 에이전트가 나눠 일하는 것과는 다르다.

8-4. 추천 구성 (문서에 있는 기능만으로)

# 1) 역할별 profile + 설명 (triage 자동 분해가 이 설명을 읽는다)
hermes profile create planner    --description "목표를 카드로 쪼갠다. 직접 구현하지 않는다."
hermes profile create coder      --description "git worktree에서 코드를 고친다."
hermes profile create researcher --description "논문·문서를 읽고 결과를 정리한다."
hermes profile create reviewer   --description "diff와 PR을 검토한다."
 
# 2) 비싼 모델은 planner, 싼 모델은 일꾼 (각 profile의 config.yaml 또는 hermes -p <이름> model)
# 3) planner에게 kanban 도구
hermes -p planner tools enable kanban
 
# 4) 프로젝트별 보드, 동시 실행 제한
hermes kanban boards create thesis --name "Thesis" --switch
#    config.yaml:  kanban: { max_in_progress: 3 }
 
# 5) gateway 하나 (디스패처 + cron + 메신저)
hermes gateway install
 
# 6) 일 넣기 → 대시보드에서 보기 → 막히면 댓글로 풀기
hermes kanban create "..." --triage
hermes dashboard

coder 카드가 Claude Code나 Codex를 쓰게 하려면, 카드에 --skill claude-code(또는 codex)와 --workspace worktree를 붙이고 본문에 claude -p ... --max-turns N을 쓰라고 적는다. 이 조합은 문서의 부품을 이어 붙인 것이고, 공식 레시피는 아니다.

출처: user-guide/profiles.md, reference/profile-commands.md, user-guide/multi-profile-gateways.md, user-guide/features/delegation.md, guides/delegation-patterns.md, user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md, ...-codex.md, user-guide/features/codex-app-server-runtime.md, user-guide/features/mixture-of-agents.md.

9. 대시보드에서 작업 중인 에이전트·모델 관리하기

9-1. 웹 대시보드

hermes dashboard              # http://127.0.0.1:9119 가 열림
hermes dashboard --port 8080 --no-open
hermes dashboard --status | --stop

한 서버가 모든 profile을 관리한다. 사이드바의 profile 전환기로 고르고, URL에 ?profile=<이름>으로 남는다.

페이지볼 수 있는 것·할 수 있는 것
Status버전, gateway 상태(PID, 연결된 플랫폼), 최근 5분 활성 세션 수, 최근 세션 20개(모델·메시지 수·토큰). 5초마다 새로고침
Sessions모든 세션(CLI·Telegram·cron 등 출처 아이콘), 실행 중인 세션에 깜빡이는 배지, 전문 검색, 이름 바꾸기, JSON 내보내기, 삭제, ▶로 이어서 대화
Chat진짜 TUI를 브라우저에 띄움. 오른쪽에 모델 선택기·세션 목록·작업 폴더 선택기
Models메인·보조 모델 지정, 모델별 토큰·비용 순위
Analytics7/30/90일 입력·출력 토큰, 캐시 적중률, 비용, 모델별 내역
Kanban보드 실시간 갱신, 드래그로 상태 변경, profile별 lane, 카드별 모델, 일꾼 로그
Cron만들기·일시정지·재개·수정·지금 실행·삭제
Profilesprofile 카드(모델·skill 수·gateway 상태), 만들기, SOUL 수정
Logsagent·errors·gateway 로그 자동 tail
SystemCPU·메모리·디스크, 업데이트, gateway 시작/정지, 백업, 체크포인트
그 밖Config(150개 이상 필드 폼), API Keys, Skills, MCP, Webhooks, Pairing, Channels

한계:

  • 대시보드에는 “이 에이전트 멈추기” 버튼이 문서에 없다. Sessions의 동작은 이름 바꾸기·내보내기·정리·삭제뿐이다. 실행 중인 하위 에이전트를 멈추고 방향을 바꾸는 기능(Stop·Steer)은 Desktop 앱, TUI(/agents), 클래식 CLI에 있다.
  • Models 페이지에서 모델을 바꾸면 새 세션에만 적용된다. 열려 있는 대화는 그 채팅에서 /model로 바꾼다. 대화 중 모델을 바꾸면 프롬프트 캐시가 초기화되어 다음 메시지가 비싸진다.
  • 비용은 채팅에서 /usage, /insights로도 본다.

원격 접속 안전:

  • 127.0.0.1에 붙어 있으면 로그인이 없다. 다른 주소(--host 0.0.0.0)에 붙이면 인증이 강제로 켜지고, 인증 수단이 없으면 아예 시작하지 않는다.
  • 대시보드는 .env(API 키)를 읽고 쓰며, kanban 플러그인 경로는 인증을 건너뛴다. 밖에서 보려면 SSH 터널이나 Tailscale을 쓰라고 문서가 권한다.

9-2. Desktop 앱

  • 여러 대화를 동시에 관리하는 채팅 중심 앱이다. 탭(Cmd+T), 새 창(Cmd+Shift+N), 명령 팔레트(Cmd+K), 세션 검색(Cmd+Shift+F).
  • 입력창 위 Subagents 영역에서 일꾼마다 Steer·Stop을 누른다. Agents와 Command Center(Cmd+.)는 문서가 “multi-agent 작업용 orchestration 화면”이라고 부른다.
  • Artifacts: 세션들에서 나온 이미지·파일·링크를 한 갤러리에 모으고, 각 항목에서 원래 세션으로 돌아간다.
  • Settings → Gateways에서 원격 Hermes(SSH, URL, Hermes Cloud)를 등록하면 한 앱에서 여러 기계의 에이전트를 본다. 단, 세션 목록은 한 번에 한 gateway씩 보인다.

출처: user-guide/features/web-dashboard.md, user-guide/configuring-models.md, user-guide/desktop.md, user-guide/multi-connection-desktop.md, user-guide/features/delegation.md.

10. Claude Code·Codex 같은 “프로젝트” 기능이 있나

부분적으로 있다. Desktop 앱에는 프로젝트 사이드바가 있고, 터미널에는 hermes project 명령이 있다. 다만 세션이 프로젝트 폴더에 따로 저장되지 않고, 하나의 DB 안에서 “어느 폴더에서 시작했나”로 묶어 보여 주는 방식이다.

있는 것

  • hermes project: 이름 붙은 작업 공간. 폴더 여러 개를 묶을 수 있다는 점은 Claude Code보다 넓다. 
    hermes project <create|list|show|add-folder|remove-folder|rename|set-primary|use|archive|restore|bind-board>
    • add-folder로 폴더·저장소를 추가하고, set-primary로 주 폴더를 정하고, use로 활성 프로젝트를 고른다.
    • bind-board로 kanban 보드를 묶으면, 카드에 일정한 worktree·branch 규칙이 붙고 주 폴더가 보드의 기본 작업 폴더가 된다.
    • 상태는 profile마다 따로다. 정확한 인자 문법(create <이름> 등)은 문서에 나오지 않으니 hermes project --help로 확인한다.
  • Desktop 프로젝트 사이드바: Group by → Projects로 바꾸면 프로젝트마다 최근 세션 3개를 보여 주고, Show all N sessions로 펼친다.
    • 프로젝트 목록은 세 곳에서 온다: hermes project로 만든 프로젝트, 내가 Hermes 세션을 연 git 저장소, 홈 디렉터리 자동 스캔으로 찾은 git 저장소.
    • 스캔 범위 설정(config.yaml 또는 Settings → Workspace): 
      desktop:
  repo_scan_enabled: true      # false면 스캔 중지
  repo_scan_roots: []          # 비우면 홈 전체를 일정 깊이까지
  repo_scan_exclude_paths: []
    • 프로젝트에서 New worktree(Cmd+Shift+B)를 누르면 새 branch의 worktree가 만들어지고, 프로젝트 아래 별도 lane으로 보인다. 리뷰 창(Cmd+G)에서 stage·commit·push·Create PR까지 한다.
    • 시작 폴더는 hermes desktop --cwd <경로>로 정한다.
  • 웹 대시보드 Chat의 작업 폴더 선택기: 같은 프로젝트·저장소 목록에 Other path… 가 붙어 있다. 휴대폰에서 원격으로 특정 폴더에 새 대화를 열 때 쓴다.
  • 터미널에서 폴더별 이어가기: 
    hermes --resume latest --in ./my-project     # 이 폴더의 마지막 세션
hermes sessions list --workspace my-project  # 폴더(git 루트 또는 cwd) 기준 필터
hermes -c                                    # 같은 터미널 창의 마지막 세션
hermes -c "세션 이름"
    세션을 이어가면 원래 작업 폴더로 돌아간다(↪ restored workspace dir: …). 원하지 않으면 --no-restore-cwd.

Claude Code·Codex와 다른 점

  • 세션은 profile마다 하나의 state.db 에 모두 들어간다. 프로젝트는 그 위에 얹은 묶음 보기다. Claude Code처럼 프로젝트 폴더별로 기록 파일이 나뉘지 않는다.
  • 메모리(MEMORY.md)도 프로젝트가 아니라 profile 단위다. 프로젝트마다 기억을 완전히 나누고 싶으면 profile을 프로젝트별로 만드는 방법밖에 없다.
  • Desktop UI에서 “폴더를 골라 프로젝트로 열기” 버튼이 있는지는 문서에 나오지 않는다. 문서에 있는 방법은 hermes project, 자동 스캔, 세션을 연 폴더다.
  • 터미널(CLI·TUI)에는 사이드바가 없다. 프로젝트 사이드바는 Desktop 전용이다.

다른 에이전트의 세션 가져오기

hermes sessions import --from claude      # ~/.claude/projects/ 읽기 (원본은 건드리지 않음)
hermes sessions import --from codex
hermes --resume @claude                    # 최근 Claude Code 세션을 Hermes에서 이어가기

사용자·어시스턴트 대화만 넘어온다. 도구 실행은 [ran tool: …] 한 줄로 줄고, 시스템 프롬프트·추론·도구 원본 출력은 빠진다.

되돌리기(체크포인트)

  • 기본은 꺼져 있다. hermes chat --checkpoints 또는 checkpoints: {enabled: true}로 켠다. 켜지 않으면 /rollback으로 되돌릴 것이 없다.
  • 파일 쓰기·패치·위험한 터미널 명령 직전에 별도 shadow git 저장소(~/.hermes/checkpoints/store/)에 스냅샷을 찍는다. 프로젝트의 진짜 .git은 건드리지 않는다.
  • /rollback, /rollback <N>, /rollback diff <N>, /rollback <N> <파일>. 컨테이너 백엔드에서는 동작하지 않는다.

출처: reference/cli-commands.md, user-guide/desktop.md, user-guide/features/web-dashboard.md, user-guide/sessions.md, user-guide/checkpoints-and-rollback.md, user-guide/git-worktrees.md.

11. 실제로 유용한 세팅 예시

A. 매일 아침 arXiv 요약을 Telegram으로

hermes cron create "0 8 * * *" \
  "Search arXiv for the 5 most notable papers from the past 24 hours on 'LLM agents' and 'mechanistic interpretability'. For each: title, authors, arXiv URL, 2-sentence contribution. Under 400 words. If none, respond with only [SILENT]." \
  --skill arxiv --name "arXiv digest" --deliver telegram --continuity
hermes cron run "arXiv digest"     # 바로 한 번 시험

전제: gateway가 돌고 있고, .env에 TELEGRAM_BOT_TOKEN과 홈 채널이 있고, arxiv skill이 설치돼 있다(hermes skills list로 확인. 기본 포함 여부는 문서에서 분명하지 않다).

B. 밤마다 vault lint, 문제 있을 때만 알림

  1. ~/.hermes/scripts/vault-check.sh에 vault의 python3 Public/_tools/lint.py를 돌리는 스크립트를 쓴다. 문제가 없으면 마지막 줄에 {"wakeAgent": false}를 출력한다.
  2. 등록한다. 
    hermes cron create "0 23 * * *" "위 lint 결과를 요약하고 가장 시급한 노트 5개를 골라라." \
  --script vault-check.sh \
  --workdir "/Users/<me>/Library/Mobile Documents/iCloud~md~obsidian/Documents/obsidian-notes" \
  --name vault-lint --deliver telegram
    깨끗한 밤에는 LLM을 부르지 않아 비용이 0이다. --workdir 덕분에 vault의 AGENTS.md를 읽는다(CLAUDE.md는 읽지 않는다는 점은 2-4절 참고).

C. 내 말투를 Hermes에도

Claude Code output style 본문을 ~/.hermes/SOUL.md로 옮긴다. vault 규칙은 SOUL.md가 아니라 vault의 AGENTS.md(또는 .hermes.md)에 둔다. 새 세션부터 반영된다.

D. 휴대폰에서 긴 작업 맡기고 기다리기

Telegram에서 /kanban create "..." --assignee coder로 카드를 만들면 그 채팅이 알림을 받는다. 일꾼이 막히면 알림이 오고, /kanban comment와 /kanban unblock으로 휴대폰에서 풀어 준다.

E. 짧은 작업은 /goal로

/goal 모든 테스트 통과시키기와 /goal gate add pytest -q를 함께 쓰면, 테스트가 통과할 때까지 같은 세션에서 계속 고친다. 기본 20턴에서 멈춘다.

12. 조심할 점

  • gateway가 핵심이다. cron, kanban 디스패처, 메신저가 모두 gateway 안에서 돈다. 맥이 잠들면 다 멈춘다. 오래 돌리려면 caffeinate나 Desktop의 Keep computer awake를 쓰고, 상시 운영은 서버를 권한다.
  • 새 도구(nvm Node, Homebrew ffmpeg 등)를 설치한 뒤에는 hermes gateway install을 다시 실행해 launchd의 PATH를 갱신한다.
  • gateway 두 개가 같은 봇 토큰을 쓰면 Telegram이 거부한다. kanban 디스패처도 gateway 하나만 맡아야 한다(나머지는 kanban.dispatch_in_gateway: false).
  • 에이전트가 메모리와 skill을 스스로 쓴다. 통제하고 싶으면 memory.write_approval, skills.write_approval을 켠다.
  • 메모리는 작고(약 3,575자) 세션 시작 때 고정된다. 큰 규칙은 AGENTS.md나 skill에 둔다.
  • profile은 보안 경계가 아니다. 파일 시스템과 로그인 정보를 공유한다.
  • subagent는 오래 가지 않는다. /stop이나 재시작에 사라진다. 오래 걸리는 일은 kanban이나 cron으로 보낸다.
  • kanban scratch 작업 공간은 끝나면 지워진다.
  • 대시보드를 0.0.0.0에 열지 않는다. .env를 다루고 kanban 경로는 인증이 없다.
  • /loop, /goal, /heartbeat, LLM cron은 회차마다 돈이 든다.
  • 메신저 대화는 저절로 초기화되지 않는다. 주제가 바뀌면 /new.

13. 문서끼리 어긋나는 곳 (2026-10-07 기준)

  • 자연어 cron 일정(daily at 9am): cron.md는 지원, automate-with-cron.md는 미지원이라고 쓴다.
  • delegate_task 기본 동시 실행 수: Features Overview는 3, delegation.md는 10.
  • 시스템 프롬프트 조립 순서: prompt-assembly.md 안의 설명과 예시, personality.md가 조금씩 다르다.
  • AGENTS.md 계층: 개발자 가이드는 “CWD only”, 사용자 가이드는 git 루트부터의 사슬이라고 쓴다.
  • 메모리 경로: 한 곳은 ~/.hermes/MEMORY.md, 나머지는 ~/.hermes/memories/.
  • cron 병렬 실행: troubleshooting 문서는 순차 실행, cron.md는 cron.max_parallel_jobs를 언급한다.

아주 짧은 암기

  • SOUL.md = 누구인가(전역, profile마다 하나), AGENTS.md = 이 폴더 규칙(한 종류만 읽음, AGENTS.md가 있으면 CLAUDE.md 무시).
  • output style은 없다. SOUL.md + /personality 가 대신한다.
  • gateway 하나가 cron·kanban·메신저를 다 돌린다. gateway가 꺼지면 다 멈춘다.
  • 여러 에이전트: 짧으면 delegate_task, 길면 profile + kanban.
  • 대시보드는 hermes dashboard(127.0.0.1:9119). 보기와 설정은 되지만 실행 중 에이전트 멈추기는 Desktop·TUI에서.
  • 프로젝트: Desktop 사이드바 + hermes project 로 부분 지원. 세션은 하나의 DB에 있고 폴더로 묶어 보여 준다.

관련 노트

출처

모두 Hermes Agent 공식 문서다. 본문 괄호 안의 경로는 GitHub NousResearch/hermes-agent 저장소 website/docs/ 기준이며, 웹 문서는 https://hermes-agent.nousresearch.com/docs/ 뒤에 확장자 없이 같은 경로를 붙이면 된다. 확인일 2026-10-07, 커밋 a50406d.