Hermes Agent GitHub: Open Source Repo, Architecture, and How to Contribute

Nous Research Hermes Agent lives at github.com/NousResearch/hermes-agent under the MIT license. The tagline is "the agent that grows with you," which refers to its closed learning loop: the agent creates skills from experience, improves them during use, and builds persistent knowledge across sessions.

The most recent release, v0.13.0 ("The Tenacity Release," May 7, 2026), landed with 864 commits since v0.12.0, 588 merged pull requests, and 282 closed issues (13 P0, 36 P1). That release brought 829 changed files, 128,366 insertions, and contributions from 295 people including co-authors.

The codebase is roughly 88% Python, 8.8% TypeScript, with small amounts of TeX, Shell, and other languages. It uses uv as its package manager and ships a pyproject.toml for Python packaging.

Before diving into the code, it helps to understand what Hermes Agent actually does. It connects to 200+ LLM models via OpenRouter, Nous Portal, OpenAI, Anthropic, NVIDIA NIM, and custom endpoints. It runs on local machines, Docker, SSH, Singularity, Modal, Daytona, and Vercel Sandbox. And it reaches users through 20 messaging platforms including Telegram, Discord, Slack, WhatsApp, Signal, and email. All of that functionality maps to specific directories in the repo.

The repo follows a flat top-level layout where each directory owns a distinct concern. Here is what you will find when you clone the repository:

Core Runtime

• agent/ contains the core agent logic, including the reasoning loop, tool dispatch, and skill execution. The transport layer lives in agent/transports/ behind a ProviderTransport ABC, with concrete implementations for Anthropic, ChatCompletions, ResponsesAPI, and Bedrock.
• run_agent.py is the agent execution runtime. cli.py is the main CLI entry point.
• batch_runner.py handles batch trajectory generation for training data.

User-Facing Interfaces

• hermes_cli/ holds CLI subcommands and the setup wizard.
• ui-tui/ is a full React/Ink terminal interface with multiline editing, slash-command autocomplete, and streaming tool output. The tui_gateway/ directory provides the Python JSON-RPC backend that powers it.
• web/ contains a web interface for browser-based access.
• gateway/ is the messaging gateway with per-platform adapters under gateway/platforms/. Each supported platform (Telegram, Discord, Slack, WhatsApp, Home Assistant, Signal, Matrix, Mattermost, email, SMS, DingTalk, WeCom, Weixin, Feishu, QQBot, BlueBubbles, Yuanbao, webhook, api_server, Google Chat) has its own adapter module.

Extensibility

• skills/ ships built-in skills organized by category directories.
• optional-skills/ contains extended skill modules that are not loaded by default.
• tools/ provides 70+ available tools. The tools/environments/ subdirectory handles terminal backends (local, Docker, SSH, Modal, Daytona, Singularity).
• plugins/ implements the plugin system, which can register CLI subcommands, receive request-scoped API hooks, prompt for required environment variables during install, and hook into session lifecycle events.
• providers/ holds LLM provider integrations behind a ProviderProfile ABC.

Infrastructure

• cron/ implements the built-in scheduling system for unattended tasks.
• acp_adapter/ and acp_registry/ handle ACP (Agent Communication Protocol) integration.
• locales/ stores internationalization files for seven languages: Chinese, Japanese, German, Spanish, French, Ukrainian, and Turkish.
• docker/ and docker-compose.yml handle container orchestration.
• tests/ contains the test suite. scripts/ holds build and utility scripts.
• website/ is the Docusaurus documentation site source.

Persist Hermes Agent files across sessions and teams

Free 50 GB workspace with MCP-ready endpoints for your agent's reads, writes, and handoffs. No credit card, no expiration.

Start 14-Day Trial

One of the most important architectural decisions in Hermes Agent is how it abstracts LLM providers. The agent/transports/ directory defines a ProviderTransport abstract base class. Every LLM provider implements this interface, which means swapping from Anthropic to OpenAI to a local Ollama endpoint requires changing configuration, not code.

The concrete transports as of v0.13.0 include:

• AnthropicTransport for Claude models via the Anthropic API
• ChatCompletionsTransport for OpenAI-compatible endpoints (covers OpenRouter, Nous Portal, NVIDIA NIM, and any OpenAI-compatible server)
• ResponsesApiTransport for the OpenAI Responses API
• BedrockTransport for AWS Bedrock

The v0.13.0 release restructured providers into a pluggable surface via a ProviderProfile ABC. This means adding a new provider is a matter of implementing the profile interface and registering it. The transport handles format conversion and HTTP communication, while the profile manages authentication, model selection, and provider-specific configuration.

This separation matters for contributors. If you want to add support for a new LLM provider, you write a transport (or reuse ChatCompletionsTransport if the API is OpenAI-compatible) and a provider profile. The rest of the agent, including tools, skills, and memory, works without modification.

For teams running Hermes at scale, this provider flexibility means you can route different tasks to different models. A summarization task might go to a fast, cheap model, while a complex reasoning task routes to a larger one. The agent handles this at the configuration level without code changes.

Hermes Agent's extensibility comes from two complementary systems: plugins and skills.

Skills are the agent's learned behaviors. The skills/ directory contains built-in skills organized by category. Each skill follows the SKILL.md format defined by the agentskills.io standard. Skills are auto-discovered from ~/.hermes/skills/ at runtime, so you can drop a new skill file into that directory and the agent picks it up on the next session.

The closed learning loop works like this: when the agent completes a complex task, it can extract the approach into a new skill. On future encounters with similar tasks, it loads that skill and improves it based on results. This is the "grows with you" part of the tagline.

Six new optional skills shipped with v0.13.0: Shopify (Admin + Storefront GraphQL), here.now, shop-app personal shopping assistant, an Anthropic financial-services bundle, kanban-video-orchestrator, and searxng-search.

Plugins extend the agent at a deeper level. Since v0.13.0, plugins can register CLI subcommands, receive request-scoped API hooks with correlation IDs, prompt for required environment variables during install, and hook into session lifecycle events via transform_llm_output and platform enablement hooks. The plugin system handles memory providers, context engines, model providers, observability, and image generation.

The distinction matters for contributors: if you want the agent to know how to do something new, write a skill. If you want to change how the agent works at the infrastructure level, write a plugin.

When your agent generates files, analysis results, or any output that needs to persist beyond a single session, you need external storage. Local file storage works for solo setups, but breaks down when you want to share outputs with teammates or hand off agent work to a human reviewer. Fastio workspaces give Hermes a persistent, shareable storage layer. Files the agent writes are indexed, searchable, and transferable. You can connect via the Fastio MCP server so the agent reads and writes to a shared workspace that humans also access through the web UI.

Contributing starts with a working dev setup. Here are the prerequisites:

• Git with --recurse-submodules support and git-lfs
• Python 3.11 or newer
• uv package manager
• Node.js 20+ (optional, only needed for browser tools and the TUI)

Clone the repo and install dependencies:

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all,dev]"

Create the user config directory and copy the example config:

mkdir -p ~/.hermes
cp cli-config.yaml.example ~/.hermes/config.yaml

Add your API keys to ~/.hermes/.env. At minimum, you need one LLM provider key (OpenRouter, Anthropic, OpenAI, or a Nous Portal key).

Verify the installation:

hermes doctor
hermes chat -q "Hello"

hermes doctor checks that dependencies, configuration, and provider connections are working. The chat -q command runs a single-turn conversation to confirm the agent can reach your configured model.

Code style rules follow PEP 8 with practical exceptions. Use pathlib.Path for file operations, open files with explicit encoding="utf-8", and never hardcode ~/.hermes paths (use the get_hermes_home() utility instead). For cross-platform compatibility, gate POSIX-only functions like os.setsid and os.killpg behind if sys.platform != "win32" checks.

The contributing guide at hermes-agent.nousresearch.com/docs/developer-guide/contributing lays out the full process. Here is the practical version.

Branch naming follows a type/description pattern:

• fix/description for bug fixes
• feat/description for new features
• docs/description for documentation
• test/description for tests
• refactor/description for restructuring

Commit messages use Conventional Commits:

feat(gateway): add WhatsApp multi-user session isolation
fix(cli): prevent crash in save_config_value when model is string

Valid scopes include cli, gateway, tools, skills, agent, install, whatsapp, and security.

Before submitting a PR, run the test suite with pytest tests/ -v and manually test the changed code paths. Your PR description should explain what changed, why, how to test it, and which platforms you tested on. Keep changes focused: one logical change per PR.

Contributing a new skill is the most common contribution path. Write a SKILL.md file following the agentskills.io format, place it in the appropriate category directory under skills/, and submit a PR. The agent auto-discovers skills at runtime, so there is no registration step.

Contributing a new tool requires implementing the tool interface and adding it to the tools/ directory. The "Adding Tools" section of the developer guide covers the specifics.

Adding a new LLM provider means implementing a ProviderProfile and, if the API is not OpenAI-compatible, a new transport class in agent/transports/.

Contribution priorities are ranked: bug fixes first, then cross-platform compatibility, security hardening, performance, new skills, new tools, and documentation last. Security vulnerabilities should be reported privately, not through public issues.

For agent workflows that produce files, reports, or creative assets, the output often needs to reach people who are not running Hermes themselves. S3 or Google Drive can handle raw storage, but Fastio workspaces add an intelligence layer: files are auto-indexed for semantic search, shareable through branded portals, and transferable between agent and human ownership. The free tier includes 50 GB of storage, included credits per month, and five workspaces with no credit card required.

The v0.13.0 "Tenacity Release" (May 7, 2026) was the largest release in the project's history. Beyond the 864 commits, several architectural changes shape where the project is heading.

Kanban multi-agent system. The /kanban command spins up a durable board where multiple Hermes workers pick up, hand off, and close tasks. The system includes heartbeat monitoring, zombie detection for stalled workers, auto-block on incomplete exits, per-task retry budgets, and a hallucination gate. This is the foundation for multi-agent workflows where several Hermes instances collaborate on a project.

Persistent goals. The /goal command locks the agent onto a target that persists across conversation turns. Previously, complex multi-step tasks could drift as context shifted. Goals act as a first-class primitive that keeps the agent on track.

Checkpoints v2. Session state persistence was rewritten with real pruning and disk guardrails. The gateway now auto-resumes interrupted sessions after a restart, which matters for long-running automations.

Security hardening. Eight P0 vulnerabilities were closed. Secret redaction is now enabled by default. Discord role-allowlists are guild-scoped (previously a CVSS 8.1 issue). WhatsApp rejects messages from unknown senders by default. TOCTOU windows in auth.json and MCP OAuth handling were closed.

New platform and localization. Google Chat became the 20th supported messaging platform. Static gateway and CLI messages now translate to seven locales.

The self-evolution companion repo at NousResearch/hermes-agent-self-evolution uses DSPy and GEPA (Genetic Evolutionary Prompt Algorithms) to optimize skills, prompts, and code. This is worth watching if you are interested in automated agent improvement rather than manual skill authoring.

For teams building on Hermes, persistent file storage becomes more important as agents run longer, produce more artifacts, and collaborate through the Kanban system. Local disk works for single-agent setups, but multi-agent teams need a shared workspace where outputs are accessible to every worker and to the humans reviewing results. Fastio's MCP server provides that shared layer with 19 consolidated tools for workspace, storage, AI, and workflow operations.