II.
Page overview
Reference · livepage:docs-hermes-research-raw-agents-md
Hermes Agent Development Guide (AGENTS.md) overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-hermes-research-raw-agents-md.
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
# Hermes Agent Development Guide (AGENTS.md)
> Source: https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md
## Overview
This 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."**
## Key Architecture Components
**Core Agent System:**
The `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.
**CLI & Terminal Interface:**
- Classic CLI uses Rich panels and prompt_toolkit with animated spinner feedback
- TUI (terminal UI) is a Node.js Ink-based React frontend communicating via JSON-RPC with a Python backend
- Dashboard embeds the real TUI through PTY bridging rather than reimplementing chat surfaces
**Plugin System:**
Two 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.
## Critical Development Rules
**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.
**Dependency Pinning:** All PyPI packages require upper bounds: `">=floor,<next_major"`. Git URLs must specify commit SHAs. This policy emerged after supply-chain compromises.
**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.
**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.
## Testing Standards
Testing 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.
**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.
## Skill Authoring Requirements
All skills require strict standards:
- Descriptions capped at 60 characters, one sentence
- Tool references must name native Hermes tools or explicit MCP servers
- Platform gating audited against actual imports
- Author credits real human contributors first
- Tests use only stdlib + pytest + unittest.mock
## Notable Systems
**Curation:** Background system tracking skill usage and auto-archiving stale agent-created skills to `~/.hermes/skills/.archive/` (never destructive).
**Cron:** Durable SQLite scheduler supporting duration phrases, "every" patterns, cron expressions, and one-shot ISO timestamps. Hard 3-minute interrupt prevents runaway loops.
**Kanban:** SQLite-backed collaborative work queue supporting multiple profiles with task assignment, dependency linking, and stale-claim reclamation.
**Prompt Caching:** Must remain valid throughout conversations -- no mid-conversation context alterations except during compression.
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-hermes-research·PageHermes Agent Deep Research