{
  "id": "page:docs-hermes-research-raw-agents-md",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/raw/agents-md.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/raw/agents-md.md",
    "sourceKind": "repo-docs",
    "title": "Hermes Agent Development Guide (AGENTS.md)",
    "displayName": "Hermes Agent Development Guide (AGENTS.md)",
    "slug": "docs/hermes-research/raw/agents-md",
    "articlePath": "wiki/docs/hermes-research/raw/agents-md.md",
    "article": "\n# Hermes Agent Development Guide (AGENTS.md)\n\n> Source: https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md\n\n## Overview\nThis comprehensive development guide instructs AI assistants and developers on working with the hermes-agent codebase. The document emphasizes: **\"Never give up on the right solution.\"**\n\n## Key Architecture Components\n\n**Core Agent System:**\nThe `AIAgent` class in `run_agent.py` implements the main conversation loop with approximately 60 initialization parameters. The agent processes tool calls iteratively until reaching maximum iterations or budget limits, following OpenAI's message format conventions.\n\n**CLI & Terminal Interface:**\n- Classic CLI uses Rich panels and prompt_toolkit with animated spinner feedback\n- TUI (terminal UI) is a Node.js Ink-based React frontend communicating via JSON-RPC with a Python backend\n- Dashboard embeds the real TUI through PTY bridging rather than reimplementing chat surfaces\n\n**Plugin System:**\nTwo distinct plugin architectures serve different purposes: general plugins for tools/hooks/lifecycle events, and specialized discovery systems for memory providers, model backends, context engines, and image generators.\n\n## Critical Development Rules\n\n**Profile Safety:** All code must use `get_hermes_home()` for state paths and `display_hermes_home()` for user messages. Hardcoding `~/.hermes` breaks multi-instance support.\n\n**Dependency Pinning:** All PyPI packages require upper bounds: `\">=floor,<next_major\"`. Git URLs must specify commit SHAs. This policy emerged after supply-chain compromises.\n\n**Tool Creation:** New core tools require registration in both `tools/your_tool.py` and `toolsets.py`. Auto-discovery handles schema collection, but toolset inclusion is a deliberate manual step.\n\n**Configuration:** Settings live in `config.yaml` (non-secrets), API keys in `.env` only. Three separate config loaders exist (CLI, tools, gateway) -- use the correct one.\n\n## Testing Standards\n\nTesting must use `scripts/run_tests.sh` rather than calling pytest directly. The wrapper enforces environment parity with CI: unset credentials, UTC timezone, C.UTF-8 locale, and subprocess-per-test isolation via an in-tree plugin.\n\n**Prohibited test patterns:** Change-detector tests that fail on routine updates (catalog snapshots, version numbers, enumeration counts) add no behavioral value and waste engineering time.\n\n## Skill Authoring Requirements\n\nAll skills require strict standards:\n- Descriptions capped at 60 characters, one sentence\n- Tool references must name native Hermes tools or explicit MCP servers\n- Platform gating audited against actual imports\n- Author credits real human contributors first\n- Tests use only stdlib + pytest + unittest.mock\n\n## Notable Systems\n\n**Curation:** Background system tracking skill usage and auto-archiving stale agent-created skills to `~/.hermes/skills/.archive/` (never destructive).\n\n**Cron:** Durable SQLite scheduler supporting duration phrases, \"every\" patterns, cron expressions, and one-shot ISO timestamps. Hard 3-minute interrupt prevents runaway loops.\n\n**Kanban:** SQLite-backed collaborative work queue supporting multiple profiles with task assignment, dependency linking, and stale-claim reclamation.\n\n**Prompt Caching:** Must remain valid throughout conversations -- no mid-conversation context alterations except during compression.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-raw-agents-md",
      "kind": "contains_page"
    }
  ]
}