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

The Hermes Agent GitHub repository at NousResearch/hermes-agent is where Nous Research develops its open-source, self-improving AI agent. This guide walks through the repo's directory layout, provider architecture, plugin system, and the exact steps for contributing skills, tools, and bug fixes back to the project.


Source: https://fast.io/resources/hermes-agent-github-open-source/
Last reviewed: 2026-05-15

## Repository Overview and Project Stats

Nous Research Hermes Agent lives at [github.com/NousResearch/hermes-agent](https://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.

## Directory Layout and What Each Module Does

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.

## Provider Architecture and Transport Layer

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.

## The Plugin and Skills System

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](https://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](https://fast.io) workspaces give Hermes a persistent, shareable storage layer. Once Intelligence is enabled on the workspace, files the agent writes are indexed, searchable, and transferable. You can connect via the [Fastio MCP server](/storage-for-agents/) so the agent reads and writes to a shared workspace that humans also access through the web UI.

## Setting Up a Development Environment

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:

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

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

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

## How to Contribute: PRs, Skills, and Tools

The contributing guide at [hermes-agent.nousresearch.com/docs/developer-guide/contributing](https://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](https://fast.io/storage-for-agents/) add an intelligence layer: once Intelligence is enabled on the workspace, files are indexed for semantic search, shareable through branded portals, and transferable between agent and human ownership. Fastio offers a 14-day Business Trial requiring a credit card.

## Key Changes in v0.13.0 and What to Watch

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](https://github.com/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](/storage-for-agents/) provides that shared layer with a consolidated MCP toolset for workspace, storage, and AI retrieval operations.

## Frequently asked questions

### Is Hermes Agent open source?

Yes. Hermes Agent is fully open source under the MIT license. The repository is at github.com/NousResearch/hermes-agent, and contributions are welcome through the standard GitHub PR process.

### Where is the Hermes Agent source code?

The source code lives at github.com/NousResearch/hermes-agent. Clone it with git clone --recurse-submodules to pull in all dependencies. The codebase is primarily Python (88%) with some TypeScript (8.8%) for the terminal UI.

### What license does Hermes Agent use?

Hermes Agent uses the MIT license, which allows commercial use, modification, distribution, and private use with minimal restrictions. Contributions to the repository must also be licensed under MIT.

### How do I contribute to Hermes Agent?

Fork the repo, create a branch using the type/description naming convention (like feat/my-feature or fix/my-bugfix), make your changes, run pytest tests/ -v, and submit a pull request. Follow the Conventional Commits format for commit messages. The contributing guide at hermes-agent.nousresearch.com/docs/developer-guide/contributing has the full details.

### How do I add a custom skill to Hermes Agent?

Write a SKILL.md file following the agentskills.io format, place it in the appropriate category directory under the skills/ folder, and submit a PR. For personal skills that do not need to be merged upstream, drop the file into ~/.hermes/skills/ and the agent auto-discovers it at runtime.

### What programming languages is Hermes Agent written in?

The codebase is 88% Python, 8.8% TypeScript, and small amounts of TeX, Shell, and other languages. The core agent logic, tools, skills, and gateway are all Python. The terminal UI (TUI) uses TypeScript with React/Ink.

### What LLM providers does Hermes Agent support?

Hermes Agent supports 200+ models through OpenRouter, plus direct integrations with Nous Portal, OpenAI, Anthropic, NVIDIA NIM, and custom endpoints. The provider architecture is pluggable, so adding new providers requires implementing a ProviderProfile interface.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.