Skip to content

feat(hermes): support Hermes agent as a sync target - #269

Merged
jeff-r2026 merged 1 commit into
Tencent:mainfrom
m0Nst3r873:feature/hermes-adapter
Jul 31, 2026
Merged

feat(hermes): support Hermes agent as a sync target#269
jeff-r2026 merged 1 commit into
Tencent:mainfrom
m0Nst3r873:feature/hermes-adapter

Conversation

@m0Nst3r873

Copy link
Copy Markdown
Collaborator

Summary

Adds support for Hermes Agent (NousResearch) as a teamai sync target. Motivating scenario: users configure Hermes via a cloud web UI, where the workspace has no .claude/ or .cursor/ directories — so every resource must land in Hermes' native, user-level locations.

Hermes was already in known-agents.ts for detection but was never wired into toolPaths, so teamai pull installed nothing for it. Hermes also uses config formats that none of the existing adapters (Claude / OpenClaw / Cursor) match.

Closes #267.

Resource mapping (all user-level, H = $HERMES_HOME, default ~/.hermes/)

Resource Target Notes
skills H/skills/<name>/SKILL.md via toolPaths.hermes.skills; Hermes scans this natively
rules H/SOUL.md teamai-managed marker block; Hermes has no rules directory
hooks H/config.yaml hooks: block + H/hooks/*.sh + H/shell-hooks-allowlist.json native YAML hook format + non-TTY pre-authorization
agent_type reported as "hermes" already worked; no code change

Key design points

  1. No settings toolPath for Hermes. Giving it one would route server-dispatched agent hooks through the JSON settings.json writer — a file Hermes never reads (silent "fake success"). All Hermes hooks go through the native config.yaml YAML path instead.
  2. Both hook mechanisms wired. The local status-report hook (reconcileHooksToAllTools) and server-dispatched agent hooks (local-agent runHookRuleCommand / removeAllAgentHooks) both dispatch to the Hermes YAML adapter for tool === 'hermes', bypassing resolveToolSettingsPath (which would otherwise throw).
  3. Comment-preserving edits. config.yaml is modified via the yaml Document API, so user comments/formatting survive pull and uninstall.
  4. Install/uninstall symmetric. Every write has a paired removal that touches only the teamai-managed marker/entry, preserving user content in SOUL.md and config.yaml.
  5. Gated on install. Writes only occur when $HERMES_HOME exists, so users who don't run Hermes never get a ~/.hermes created. uninstall --agent <other> never touches Hermes.

Files

New: src/hermes-home.ts, src/hermes-config.ts, src/hermes-hooks.ts, src/__tests__/hermes-config.test.ts.
Changed: src/types.ts, src/usage-tracker.ts, src/resources/rules.ts, src/hooks.ts, src/local-agent.ts, src/uninstall.ts.

Test Plan

  • npx tsc --noEmit — zero errors
  • npm run build — success
  • npx vitest run — 1884 passed (incl. 16 new Hermes tests)
  • E2E real CLI pull: skills → .hermes/skills/, rules → .hermes/SOUL.md block, hooks → config.yaml + .hermes/hooks/*.sh (executable) + allowlist
  • E2E: user content in SOUL.md / config.yaml (incl. comments) preserved
  • E2E: second pull is idempotent (no duplicate blocks/entries)
  • E2E: uninstall --agent hermes removes all three resource types; full uninstall symmetric; user content kept
  • E2E: Hermes not installed → pull does not create ~/.hermes
  • E2E: custom HERMES_HOME → install gate and write both honor it
  • E2E: marker injected in a rule body is sanitized (block boundaries intact)

🤖 Generated with Claude Code

Adapt teamai to Hermes Agent (NousResearch). Resources land in
Hermes-native, user-level locations under $HERMES_HOME (default ~/.hermes):

- skills  -> .hermes/skills/ (via toolPaths)
- rules   -> .hermes/SOUL.md (teamai-managed marker block)
- hooks   -> config.yaml hooks block + .hermes/hooks/*.sh script
             + shell-hooks-allowlist.json pre-authorization

Both hook paths are wired to Hermes' native YAML format: the local
status-report hook (reconcileHooksToAllTools) and server-dispatched
agent hooks (local-agent runHookRuleCommand), instead of the JSON
settings.json path Hermes never reads.

config.yaml is edited via the yaml Document API so user comments and
formatting survive. Install/uninstall are symmetric and only touch the
teamai-managed block, preserving user content. Writes are gated on the
.hermes home existing, so users who don't run Hermes are never touched.

Adds 16 unit tests for the config/SOUL/hook read-modify-write logic.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jeff-r2026
jeff-r2026 merged commit e35f2db into Tencent:main Jul 31, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Enhancement] 支持 Hermes Agent(NousResearch)作为同步目标

2 participants