ngn-agent/.planning/research/hermes/EXTENSIBILITY.md

Hermes Agent: Extensibility (Plugins, MCP, Profiles)

Plugin System

Plugins add tools, hooks, CLI commands, and slash commands without modifying Hermes core.

Structure

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # Manifest
├── __init__.py      # register(ctx) — wires schemas to handlers
├── schemas.py       # Tool schemas (what the LLM sees)
└── tools.py         # Tool handlers (what runs when called)

Capabilities

Capability	API	Use for ngn-agent
Add tools	ctx.register_tool()	Jira/Confluence tools
Add hooks	ctx.register_hook()	Log infra commands, enforce guardrails
Add slash commands	ctx.register_command()	/jira, /confluence shortcuts
Add CLI commands	ctx.register_cli_command()	ngn check-health, ngn report
Inject messages	ctx.inject_message()	Alert the agent mid-conversation
Bundle skills	ctx.register_skill()	Ship infra skills with plugin
LLM access	ctx.llm.complete()	Run LLM calls from plugin code
Register platform	ctx.register_platform()	Custom gateway channels

Plugin Lifecycle

hermes plugins                    # Interactive toggle UI
hermes plugins list               # Table: enabled/disabled/not enabled
hermes plugins install user/repo  # Install from GitHub
hermes plugins enable my-plugin   # Add to allow-list

Plugins are opt-in: plugins.enabled in config.yaml

Available Hooks

Hook	Fires	Use
pre_tool_call	Before any tool	Log all commands, check IAM scope
post_tool_call	After any tool	Capture tool results for audit
pre_llm_call	Once per turn	Inject context like current IAM role
post_llm_call	After LLM turn	Save learnings
on_session_start	New session	Set up context, load env facts
on_session_end	Session ends	Archive session, capture memory

MCP (Model Context Protocol)

MCP servers add external tools by declaring them in config.yaml:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

No plugin code needed — just config. Tools are auto-discovered and registered alongside built-in tools. Perfect for Jira, Confluence, or any MCP-compatible service.

Profiles (Multi-Agent)

Profiles are separate Hermes homes with their own config, .env, memory, skills, and gateway.

hermes profile create coder       # Create profile + "coder" CLI command
coder chat                        # Chat with coder profile
coder gateway start               # Start coder's gateway separately

hermes profile list               # Show all profiles
hermes profile use coder          # Set as sticky default

Storage

~/.hermes/                    # Default profile
~/.hermes/profiles/coder/     # Named profile
~/.hermes/profiles/research/  # Another profile

Profile Sharing

hermes profile export coder           # Export as tar.gz
hermes profile install github.com/you/research-bot  # Install from git

Each profile can have different:

• LLM providers/models
• Bot tokens (separate Telegram bot per profile)
• Skills
• Memory
• Cron jobs
• Security settings

ngn-agent Implications

• Don't build a plugin system — Hermes already has one
• Use MCP for Jira/Confluence — no code, just config
• Create a custom plugin for ngn-agent-specific hooks:
  • pre_tool_call hook to verify IAM scope before AWS commands
  • on_session_start hook to inject current environment context
  • post_tool_call hook to audit all infra actions
• Use profiles if ngn-agent needs separate identities (e.g., dev vs prod gateways)
• Profile isolation means we can run multiple ngn-agent instances independently