feat: add Hermes Agent support — configs, plugin, README

[tayuLuc]

What / Why / How

Adds Hermes Agent support to context-mode — the first upstream integration for this platform.

What: Configuration files, plugin, and README updates to support context-mode on Hermes Agent.

Why: Hermes Agent is an open-source AI agent framework by Nous Research with 130k+ GitHub stars, running across CLI, Telegram, Discord, and other platforms. It natively supports MCP servers and has a Python plugin system — making it a natural fit for context-mode.

How:

• configs/hermes/AGENTS.md — routing rules for Hermes (same pattern as OpenClaw/OpenCode configs)
• plugins/context-saver/ — Hermes Agent plugin with pre_tool_call and pre_llm_call hooks that enforce context-mode routing
• README updates — Hermes added to the platform table and install section

No dependency on context-mode's npm package — the plugin uses Hermes' native execute_code as the sandbox, making it zero-dependency.

Affected platforms

• Claude Code
• Cursor
• VS Code Copilot (GitHub Copilot)
• JetBrains Copilot
• Gemini CLI
• Qwen Code
• OpenCode
• KiloCode
• Codex CLI
• OpenClaw (Pi Agent)
• Pi
• Kiro
• Antigravity
• Zed
• Hermes Agent (new)
• All platforms

Test plan

1. Install context-mode as MCP server: hermes mcp add context-mode -- npx -y context-mode
2. Copy plugin to ~/.hermes/plugins/context-saver/
3. Enable in config: plugins.enabled: [context-saver]
4. Restart: hermes gateway restart
5. Verify pre_tool_call blocks curl — model redirects to ctx_execute
6. Verify ctx stats / ctx doctor utility commands work via MCP

Checklist

• Tests added/updated (TDD: red → green)
• npm test passes (no JS/TS changes — Python plugin only)
• npm run typecheck passes
• Docs updated if needed (README, platform-support.md)
• No Windows path regressions (forward slashes only)
• Targets next branch (unless hotfix)

Cross-platform notes

The plugin is pure Python 3.9+ — no native dependencies. Hermes Agent runs on macOS, Linux, and Windows (WSL).

[mksglu]

Why is it py?

[tayuLuc]

Why is it py?

It's dictated by the Hermes runtime.

Hermes Agent is a Python-based application, and its plugin system (pre_tool_call, pre_llm_call, etc.) is designed to be Python modules loaded directly into its execution environment. The official Hermes documentation for building plugins exclusively uses the __init__.py + plugin.yaml Python pattern.

To hook into the agent's tool selection process (e.g., intercepting a curl call before it happens and telling the model to use ctx_execute instead), the hook must run in the Hermes Python process.

This is analogous to the existing plugins in this repo: Cursor's .claude-plugin/ and OpenClaw's .openclaw-plugin/ are written in JavaScript/TypeScript because they run in the Node.js / VS Code environments. .hermes-plugin/ is Python because it runs in the Hermes Python runtime.

[EPPCOM-Solutions]

HOLD — three blockers before this can merge

The approach (Python plugin for a Python-native runtime) is architecturally defensible — same rationale as OpenClaw's JS plugin. But the PR has gaps that need addressing:

Blocker 1: Verify Hermes Agent exists and hook API matches
The PR claims Nous Research / 130k+ GitHub stars. This cannot be verified from the diff. Please link:

• The actual GitHub repo URL
• The official plugin documentation URL (you reference build-a-hermes-plugin.md in the PR body but don't link it)
• Confirmation that pre_tool_call, pre_llm_call, and register(ctx) match the real API signatures
• That the {"action": "block", "message": ...} return schema is respected by the runtime

Blocker 2: TDD gate — tests required
Your own checklist has [ ] Tests added/updated unchecked. Every other platform in this repo has tests/adapters/<platform>.test.ts. At minimum add a tests/adapters/hermes.test.ts covering:

• pre_tool_call blocks disallowed tools
• pre_tool_call allows tools in ALLOWED list
• pre_llm_call injects guidance on first turn only
• _GUIDANCE_SHOWN does not re-inject on subsequent turns

(Can be Python stubs tested via subprocess or JS stubs — your call, but tests must exist.)

Blocker 3: Memory leak in _GUIDANCE_SHOWN
_GUIDANCE_SHOWN is a module-level dict that grows unbounded across sessions with no eviction. In a long-running gateway process (days/weeks uptime) this leaks. Cap it:

if len(_GUIDANCE_SHOWN) > 1000:
    _GUIDANCE_SHOWN.clear()  # simple LRU approximation

Minor fixes (not blockers):

• README has a duplicate <sup>(CentOS, RHEL, Alpine)</sup></summary> line — merge artifact, remove it
• Link the Hermes plugin docs URL inline in the README install section

Happy to re-review once these are addressed — the core idea is sound.

[mksglu]

@tayuLuc If we implement this, you’ll be responsible for any future issues, bugs, and improvements. Do you agree to this, since I don’t use Hermes Agent?

[tayuLuc]

@mksglu

Fair points on the blockers. The plugin isn't ready to merge.

Still, I think there's value in keeping this PR visible — it's a way for the Hermes community to discover context-mode.

For the repo side, maybe just a note in the README that Hermes support is in progress? That way when someone searches for it, they find the trail.

I'll keep working on the plugin locally, and if there's enough traction, we can address the blockers with proper tests and a clean implementation.

[mksglu]

@tayuLuc Close the PR and work on it yourself; reopen the PR when you're ready

[SoTHISIsFitness]

there's definitely interest in this... it goes a long way toward solving a token-burning problem in Hermes-Agent, so definitely would love to see this pursued. And to be fair, Blocker 1 is... not really a blocker, more the bot not understanding that... yeah - Hermes does, in fact, exist. Blocker 2 is just a missing test, but... isn't there a test in the commit? And blocker 3 just requires capping the memory leak which the bot even showed a basic approximation of 😅 so... this feels like it's pretty close? Or did I glance too quickly?

[mksglu]

How you think about the PR's testing process? What should we do for that? How's going on your side in here? @tayuLuc

[tayuLuc]

@mksglu I've been thinking about the testing setup. pytest is probably the way to go — same pattern as vitest, auto-discovery, fixtures, exit codes. Can keep it inside the vitest call or spin it out as a separate CI step.

[mksglu]

Why is it closed. @tayuLuc

[tayuLuc]

I accidentally did the wrong merge of commits and force push it.

The feat/hermes-agent-support branch was force-pushed or recreated.

[mksglu]

OK. Let's reopen. We need manually testing when it's ready. @tayuLuc