# 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

```bash
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:

```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.

```bash
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
```bash
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