The Problem

Teams that need a persistent, multimodal AI assistant often cobble together separate chat front‑ends, tool‑calling wrappers, and ad‑hoc storage. Maintaining that glue code across Slack, Telegram, or a local terminal becomes a source of drift and hidden technical debt.

What This Does

hermes-agent is a self‑contained portfolio of 13 related projects that together provide a “grow‑with‑you” AI agent. The core CLI lives in cli.py and boots the agent, loads configuration from hermes_cli/config.py, and dispatches commands to the gateway (gateway/run.py). Skill definitions (e.g., productivity, research) reside under skills/ and are discovered at runtime; the gateway translates inbound messages from platforms (Telegram, Slack, WhatsApp, etc.) into a unified internal format. The agent can invoke large language models via the adapters in agent/ (Anthropic, OpenAI, custom endpoints) and stores conversation history in a SQLite‑backed vector store (FTS5) for cross‑session recall.

How It Is Wired

  1. Entry point – hermes installs a wrapper that runs python -m hermes_cli.main. The main function (≈4 900 LOC) parses CLI arguments and eventually calls run in cli.py.
  2. run (≈3 874 LOC) builds a Config object via hermes_cli/config.py (46 inbound imports, only 2 outbound) and creates a Gateway (gateway/run.py).
  3. gateway/run.py starts the gateway process (start function, 582 LOC) which: loads platform plugins (gateway/platforms/*) establishes a session (gateway/session.py) that reads/writes the SQLite DB (honcho_integration/session.py) – 291 filesystem calls and 22 DB calls are traced from entry to exit.
  4. Incoming messages are normalized by gateway/config.py and routed to the agent core (agent/*). The most used internal functions are print (306 call sites) and load_config (35 sites).
  5. Model inference is performed through the adapter layer (agent/anthropic_adapter.py, agent/auxiliary_client.py). Nine functions invoke a remote LLM, each passing the current conversation context.
  6. Side‑effects: the agent writes transcripts (run_agent.py), updates the vector store, and may launch subprocesses (e.g., subprocess.run for git operations).

The hub modules hermes_cli/config.py, gateway/config.py, and tools/registry.py each have >40 inbound imports; changes here have a high blast radius. Circular import cycles involve run_agent.py, tools/registry.py, and tools/terminal_tool.py, increasing maintenance risk.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/hermes-agent
cd hermes-agent

# One‑line installer (handles Python, Node, and the hermes command)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Reload shell to expose the hermes CLI
source ~/.bashrc   # or ~/.zshrc

# Run the interactive terminal UI
hermes

Configuration lives in .env.example (copy to .env and fill API keys). The CLI reads this via hermes_cli/config.py. Platform credentials (Telegram bot token, Slack app token, etc.) are also read from environment variables; the gateway will refuse to load a platform if the corresponding env var is missing.

To add a new skill, drop a Python module under skills/ that implements the Skill interface defined in agent/skill_commands.py. The repository’s test suite (tests/) validates skill loading and platform adapters.

Real‑World Use

A product team can deploy the agent on a cheap VPS, expose it to Slack and Telegram, and let it autonomously file daily status reports. The agent’s cron scheduler (cron/jobs.py) can trigger a run_conversation that pulls data from an internal API (via a tool defined in tools/terminal_tool.py) and posts a summarized message to the configured channels, all without manual scripting.

Code Health & Issues

  • High – Pin third‑party GitHub Actions to commit SHA (.github/workflows/*).
  • Medium – Declare least‑privilege GITHUB_TOKEN permissions (tests.yml).
  • Medium – Enable Dependabot or Renovate for automatic updates.
  • Medium – Add a dependency‑vulnerability scan step in CI.
  • Medium – Set persist-credentials: false on checkout (deploy-site.yml).
  • Medium – Review postinstall script in package.json; move work to an explicit build step or disable scripts in CI.
  • Low – Add job timeouts (deploy-site.yml).
  • Low – Provide editor/formatter conventions (.editorconfig, formatter config).

Static analysis also flagged:

  • Broad except: clauses in gateway/config.py, hermes_cli/config.py, tools/registry.py (15 occurrences).
  • Deep nesting (max depth 6) in several config files and gateway/platforms/base.py (19 occurrences).
  • Oversized modules (hermes_cli/config.py, run_agent.py, hermes_cli/auth.py) exceeding 1 000 lines, increasing cognitive load.
  • Import cycles involving tools/registry.py, run_agent.py, tools/terminal_tool.py.
  • File opens without context managers in tools/terminal_tool.py and hermes_cli/auth.py.

These findings are factual outputs of the analysis pipeline; no additional speculative issues are reported.

The Bottom Line

hermes-agent delivers a feature‑rich, extensible AI assistant with a solid test base and clear entry points, but its architecture contains several high‑impact hubs and import cycles that raise the cost of change. Teams comfortable managing Python‑centric monorepos and willing to address the highlighted health items can leverage it for multi‑platform, self‑improving agents without building the plumbing from scratch.