Built-in Plugins

anchor alias

Built-in Plugins

Hermes는 repository에 bundled된 작은 plugin set을 함께 제공합니다. 이 plugin들은 <repo>/plugins/<name>/ 아래에 있으며, user-installed plugins가 있는 ~/.hermes/plugins/와 함께 load됩니다. third-party plugin과 같은 plugin surface, 즉 hooks, tools, slash commands를 사용하지만 in-tree에서 유지보수됩니다.

일반 plugin system은 Plugins를 참고하고, 직접 plugin을 만들려면 Build a Hermes Plugin을 참고하세요.

How discovery works

PluginManager는 다음 네 source를 순서대로 scan합니다.

1. Bundled - <repo>/plugins/<name>/ (이 문서에서 다루는 plugin)
2. User - ~/.hermes/plugins/<name>/
3. Project - ./.hermes/plugins/<name>/ (HERMES_ENABLE_PROJECT_PLUGINS=1 필요)
4. Pip entry points - hermes_agent.plugins

이름이 충돌하면 뒤쪽 source가 이깁니다. 예를 들어 사용자가 만든 disk-cleanup plugin은 bundled plugin을 대체합니다.

plugins/memory/와 plugins/context_engine/은 bundled scanning에서 의도적으로 제외됩니다. memory providers와 context engines는 single-select provider이고, 각각 hermes memory setup / config의 context.engine으로 구성되기 때문에 별도의 discovery path를 사용합니다.

Bundled plugins are opt-in

Bundled plugins는 비활성 상태로 함께 배포됩니다. Discovery에는 잡히므로 hermes plugins list와 interactive hermes plugins UI에 표시되지만, 명시적으로 enable하기 전에는 아무것도 load되지 않습니다.

hermes plugins enable disk-cleanup

또는 ~/.hermes/config.yaml에서 설정할 수 있습니다.

plugins:
  enabled:
    - disk-cleanup

이는 user-installed plugins와 같은 mechanism입니다. Bundled plugins는 fresh install에서도, 기존 사용자가 새 Hermes로 upgrade할 때도 자동으로 enable되지 않습니다. 항상 명시적으로 opt in해야 합니다.

Bundled plugin을 다시 끄려면:

hermes plugins disable disk-cleanup
# or: remove it from plugins.enabled in config.yaml

Currently shipped

repo의 plugins/ 아래에는 다음 bundled plugins가 포함되어 있습니다. 모두 opt-in이며 hermes plugins enable <name>으로 enable합니다.

Plugin	Kind	Purpose
disk-cleanup	hooks + slash command	session 중 만들어진 ephemeral files를 자동 추적하고 session 종료 시 정리
observability/langfuse	hooks	turns / LLM calls / tools를 Langfuse에 trace
spotify	backend (7 tools)	Spotify playback, queue, search, playlists, albums, library native 제어
google_meet	standalone	Meet call 참여, live-caption transcription, 선택적 realtime duplex audio
image_gen/openai	image backend	OpenAI gpt-image-2 image generation backend (FAL 대안)
image_gen/openai-codex	image backend	Codex OAuth를 통한 OpenAI image generation
image_gen/xai	image backend	xAI grok-2-image backend
hermes-achievements	dashboard tab	실제 Hermes session history에서 생성되는 Steam-style collectible badges
kanban/dashboard	dashboard tab	multi-agent dispatcher용 Kanban board UI: tasks, comments, fan-out, board switching. Kanban Multi-Agent 참고.

Memory providers(plugins/memory/*)와 context engines(plugins/context_engine/*)는 Memory Providers에 별도로 나열되어 있습니다. 각각 hermes memory와 hermes plugins로 관리됩니다. 아래에는 long-running hooks 기반 plugin 두 개의 detail을 설명합니다.

disk-cleanup

session 중 생성되는 ephemeral files, 예를 들어 test scripts, temp outputs, cron logs, stale chrome profiles를 자동 추적하고 제거합니다. agent가 별도 tool 호출을 기억하지 않아도 됩니다.

How it works:

Hook	Behaviour
post_tool_call	write_file / terminal / patch가 HERMES_HOME 또는 /tmp/hermes-* 아래에 test_*, tmp_*, *.test.*에 맞는 file을 만들면 조용히 test / temp / cron-output으로 track합니다.
on_session_end	해당 turn에서 test files가 auto-track되었다면 safe quick cleanup을 실행하고 한 줄 summary를 log합니다. 그 외에는 조용히 지나갑니다.

Deletion rules:

Category	Threshold	Confirmation
test	every session end	Never
temp	>7 days since tracked	Never
cron-output	>14 days since tracked	Never
empty dirs under HERMES_HOME	always	Never
research	>30 days, beyond 10 newest	Always (deep only)
chrome-profile	>14 days since tracked	Always (deep only)
files >500 MB	never auto	Always (deep only)

Slash command - /disk-cleanup은 CLI와 gateway session 양쪽에서 사용할 수 있습니다.

/disk-cleanup status                     # breakdown + top-10 largest
/disk-cleanup dry-run                    # preview without deleting
/disk-cleanup quick                      # run safe cleanup now
/disk-cleanup deep                       # quick + list items needing confirmation
/disk-cleanup track <path> <category>    # manual tracking
/disk-cleanup forget <path>              # stop tracking (does not delete)

State - 모든 state는 $HERMES_HOME/disk-cleanup/에 저장됩니다.

File	Contents
tracked.json	category, size, timestamp가 포함된 tracked paths
tracked.json.bak	위 file의 atomic-write backup
cleanup.log	모든 track / skip / reject / delete에 대한 append-only audit trail

Safety - cleanup은 HERMES_HOME 또는 /tmp/hermes-* 아래 path만 건드립니다. Windows mounts(/mnt/c/...)는 거부합니다. 잘 알려진 top-level state dirs(logs/, memories/, sessions/, cron/, cache/, skills/, plugins/, disk-cleanup/ 자체)는 비어 있어도 절대 제거하지 않습니다. fresh install이 첫 session end에서 비워지는 일을 막기 위함입니다.

Enabling: hermes plugins enable disk-cleanup 또는 hermes plugins에서 checkbox 선택.

Disabling again: hermes plugins disable disk-cleanup.

observability/langfuse

Hermes turns, LLM calls, tool invocations를 open-source LLM observability platform인 Langfuse에 trace합니다. turn마다 span 하나, API call마다 generation 하나, tool call마다 tool observation 하나가 만들어집니다. usage totals, per-type token counts, cost estimates는 Hermes의 canonical agent.usage_pricing 값에서 나오므로 Langfuse dashboard는 hermes logs와 같은 breakdown(input / output / cache_read_input_tokens / cache_creation_input_tokens / reasoning_tokens)을 봅니다.

이 plugin은 fail-open 방식입니다. SDK가 없거나, credential이 없거나, 일시적인 Langfuse 오류가 나도 hook 안에서 silent no-op으로 처리됩니다. agent loop에는 영향을 주지 않습니다.

Setup (interactive - recommended):

hermes tools          # Langfuse Observability -> Cloud or Self-Hosted

wizard가 key를 수집하고, langfuse SDK를 pip install하며, observability/langfuse를 plugins.enabled에 추가합니다. Hermes를 restart하면 다음 turn부터 trace가 전송됩니다.

Setup (manual):

pip install langfuse
hermes plugins enable observability/langfuse

그다음 credential을 ~/.hermes/.env에 넣습니다.

HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com   # or your self-hosted URL

How it works:

Hook	Behaviour
pre_api_request / pre_llm_call	per-turn root span인 "Hermes turn"을 열거나 재사용합니다. 이 API call에 대한 generation child observation을 시작하고 serialized recent messages를 input으로 기록합니다.
post_api_request / post_llm_call	generation을 닫고 usage_details, cost_details, finish_reason, assistant output + tool calls를 붙입니다. tool call이 없고 content가 비어 있지 않으면 turn도 닫습니다.
pre_tool_call	sanitized args로 tool child observation을 시작합니다.
post_tool_call	sanitized result로 tool observation을 닫습니다. read_file payload는 huge file read가 HERMES_LANGFUSE_MAX_CHARS 아래에 머물도록 head + tail + omitted-line count로 summarize됩니다.

Session grouping은 Hermes session ID 또는 sub-agent task ID를 기준으로 langfuse.propagate_attributes를 사용합니다. 따라서 하나의 hermes chat session에 속한 trace는 Langfuse에서도 하나의 session 아래에 묶입니다.

Verify:

hermes plugins list                 # observability/langfuse should show "enabled"
hermes chat -q "hello"              # check the Langfuse UI for a "Hermes turn" trace

Optional tuning (.env에서 설정):

Variable	Default	Purpose
HERMES_LANGFUSE_ENV	empty	trace environment tag (production, staging, ...)
HERMES_LANGFUSE_RELEASE	empty	release/version tag
HERMES_LANGFUSE_SAMPLE_RATE	1.0	SDK에 전달하는 sampling rate (0.0-1.0)
HERMES_LANGFUSE_MAX_CHARS	12000	message content / tool args / tool results의 per-field truncation
HERMES_LANGFUSE_DEBUG	false	agent.log에 verbose plugin logging

Hermes-prefixed env vars와 standard SDK env vars(LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL)를 모두 인식합니다. 둘 다 있으면 Hermes-prefixed 값이 우선합니다.

Performance: Langfuse client는 첫 hook call 이후 cache됩니다. credential이나 SDK가 없다는 판단도 cache되므로 이후 hook은 env var 재확인이나 config reload 없이 빠르게 return합니다.

Disabling: hermes plugins disable observability/langfuse. plugin module은 여전히 discovery되지만, 다시 enable하기 전까지 module code는 실행되지 않습니다.

google_meet

agent가 Google Meet call에 참여하고, transcribe하고, 회의에 참여할 수 있게 합니다. 회의 note를 남기고, 오간 내용을 summarize하며, 특정 point에 follow-up하고, 선택적으로 TTS를 통해 reply를 call에 다시 말할 수 있습니다.

What it adds:

• browser automation으로 Meet URL에 참여하는 headless virtual participant
• 구성된 STT provider를 통한 meeting audio live transcription
• agent가 들은 내용을 바탕으로 행동할 수 있는 meet_summarize / meet_speak / meet_followup toolset
• transcript, speaker-attributed notes, action items 같은 post-meeting artifacts를 ~/.hermes/cache/google_meet/<meeting_id>/ 아래에 저장

Setup:

hermes plugins enable google_meet
# Prompts you to sign in via the plugin's OAuth flow on first use.
# needs a Google account with Meet access. Host approval may be required
# if the meeting enforces "only invited participants can join".

chat에서 사용하는 예:

"Join meet.google.com/abc-defg-hij and take notes. After the call, send me a summary with action items."

agent는 meeting join을 시작하고, call이 진행되는 동안 transcription을 context로 stream하며, meeting이 끝나거나 사용자가 멈추라고 할 때 structured summary를 생성합니다.

When to use it: async 참석자를 위해 bot이 transcribe + summarize해 주면 좋은 recurring standups, structured notes가 필요한 deposition-style interviews, Fireflies / Otter / Grain을 대신할 수 있는 경우. AI가 듣고 있으면 안 되는 회의에는 enable하지 마세요.

Disabling: hermes plugins disable google_meet. cached transcripts와 recordings는 사용자가 제거할 때까지 ~/.hermes/cache/google_meet/에 남습니다.

hermes-achievements

dashboard에 Steam-style achievements tab을 추가합니다. 실제 Hermes session history에서 생성되는 60개 이상의 collectible, tiered badges를 제공합니다. tool-chain feats, debugging patterns, vibe-coding streaks, skill/memory usage, model/provider variety, weekend/night sessions 같은 lifestyle quirks를 다룹니다. 원래 @PCinkusz가 external plugin으로 만들었고, Hermes feature 변화와 맞춰 유지되도록 in-tree로 들어왔습니다.

How it works:

• dashboard backend에서 전체 ~/.hermes/state.db session history를 scan합니다.
• per-session stats는 (started_at, last_active) fingerprint로 cache되므로, subsequent scan에서는 새 session이나 변경된 session만 다시 analyze합니다.
• 첫 scan은 background thread에서 실행됩니다. session이 수천 개 있는 database에서도 dashboard가 scan 완료를 기다리며 block되지 않습니다.
• unlock state는 $HERMES_HOME/plugins/hermes-achievements/state.json에 persist됩니다.

Tier progression: Copper -> Silver -> Gold -> Diamond -> Olympian. 각 card는 정확히 어떤 metric을 추적하는지 보여주는 "What counts" section을 제공합니다.

Achievement states:

State	Meaning
Unlocked	하나 이상의 tier를 달성한 상태
Discovered	알려진 achievement이며 progress가 보이지만 아직 달성하지 않은 상태
Secret	Hermes가 history에서 관련 signal을 처음 감지할 때까지 숨겨진 상태

API - routes는 /api/plugins/hermes-achievements/ 아래에 mount됩니다.

Endpoint	Purpose
GET /achievements	per-badge unlock state가 포함된 full catalog. 첫 cold scan 중에는 pending placeholder를 반환합니다.
GET /scan-status	background scanner 상태: idle / running / failed, last duration, run count
GET /recent-unlocks	가장 최근 unlock된 badge 20개, newest first
GET /sessions/{id}/badges	특정 session 하나에서 주로 earned된 badges
POST /rescan	manual synchronous rescan. 사용자가 rescan button을 눌렀을 때 사용하며 blocking입니다.
POST /reset-state	unlock history와 cached snapshot을 지웁니다.

State files - $HERMES_HOME/plugins/hermes-achievements/ 아래에 저장됩니다.

File	Contents
state.json	어떤 badge를 언제 earn했는지에 대한 unlock history. Hermes update 후에도 유지됩니다.
scan_snapshot.json	마지막으로 완료된 scan payload. dashboard load 시 즉시 제공됩니다.
scan_checkpoint.json	fingerprint별 per-session stats cache. warm rescan을 빠르게 만듭니다.

Performance notes:

• 약 8,000개 session에 대한 cold scan은 몇 분 걸립니다. 첫 dashboard request에서 background thread로 실행되며, UI는 pending placeholder를 보여주고 /scan-status를 polling합니다.
• Cold scan 중 incremental results - scanner는 약 250 sessions마다 partial snapshot을 publish합니다. dashboard refresh 때마다 scan 진행에 따라 더 많은 badge unlock이 보입니다.
• warm rescan은 started_at + last_active fingerprint가 checkpoint와 일치하는 모든 session의 per-session stats를 재사용하므로 큰 history에서도 몇 초 안에 끝납니다.
• in-memory snapshot TTL은 120초입니다. stale request는 이전 snapshot을 즉시 제공하고 background refresh를 시작합니다. TTL 만료 때문에 사용자가 spinner를 기다릴 필요가 없습니다.

Enabling: enable할 것이 없습니다. hermes-achievements는 dashboard-only plugin입니다(lifecycle hook 없음, model-visible tool 없음). hermes dashboard 첫 launch에서 tab으로 자동 등록됩니다. plugins.enabled config는 lifecycle/tool plugins만 gate하며, dashboard plugins는 dashboard/manifest.json만으로 discovery됩니다.

Opting out: plugins/hermes-achievements/dashboard/manifest.json을 삭제하거나 이름을 바꾸세요. 또는 ~/.hermes/plugins/hermes-achievements/에 같은 이름의 user plugin을 두고 dashboard를 제공하지 않게 override할 수 있습니다. $HERMES_HOME/plugins/hermes-achievements/ 아래 state files는 남으므로 재설치해도 unlock history는 유지됩니다.

Adding a bundled plugin

Bundled plugin은 다른 Hermes plugin과 정확히 같은 방식으로 작성합니다. Build a Hermes Plugin을 참고하세요. 차이는 다음뿐입니다.

• directory가 ~/.hermes/plugins/<name>/이 아니라 <repo>/plugins/<name>/에 있습니다.
• hermes plugins list에서 manifest source가 bundled로 표시됩니다.
• 같은 이름의 user plugin이 bundled version을 override합니다.

다음 조건을 만족하면 bundled plugin 후보로 적합합니다.

• optional dependency가 없거나 이미 pip install .[all] dependency에 포함되어 있습니다.
• behaviour가 대부분의 사용자에게 유용하고 opt-in으로 제공하기 적합합니다.
• agent가 직접 기억해서 invoke해야 하는 logic이 아니라 lifecycle hook에 자연스럽게 붙습니다.
• model-visible tool surface를 넓히지 않으면서 core capability를 보완합니다.

반대로 third-party integration with API keys, niche workflow, 큰 dependency tree, 기본 agent behaviour를 의미 있게 바꾸는 기능은 bundled가 아니라 user-installable plugin으로 남겨야 합니다.