DEV Community: MLisanti_Dev

title: From Zero to Hermes Agent in 3 Days — An Honest Beginner's Journey

MLisanti_Dev — Fri, 29 May 2026 22:40:59 +0000

This is a submission for the Hermes Agent Challenge: Write About Hermes Agent

The Honest Version Nobody Tells You

Most tutorials start with a clean Linux machine, a working API key, and someone who already knows what they're doing.

This is not that tutorial.

This is the story of building a real project with Hermes Agent starting from a Windows PC with virtualisation disabled in the BIOS, zero Linux environment, and a deadline three days away.

I built repo-audit-agent — a tool that uses Hermes Agent to perform first-pass technical reviews of GitHub repositories. Here's what I actually learned along the way.

Day 1: The Environment Problem

Before I could even think about Hermes Agent, I needed a Linux environment.

My Windows machine had WSL2 partially configured but virtualisation was disabled at the BIOS level — a common corporate lockdown. So WSL2 was out.

I tried:

Google Colab — works, but resets every session. You reinstall everything every time you open it.
Replit — changed their UI completely, now pushes everyone toward their own AI agent.
CloudShell on AWS — only 1GB of disk space. Hermes Agent needs more.

What finally worked: AWS EC2 t2.micro free tier.

A real Ubuntu server in the cloud, persistent across sessions, 6.6GB of disk, always available. Once I understood this was the right environment, everything else followed.

Lesson learned: Don't fight your local environment. Cloud VMs exist precisely for this.

Day 2: Installing Hermes Agent

Once I had an EC2 instance running Ubuntu Server, installation was one command:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer is genuinely impressive. It:

Detects your OS and installs the right Python version via uv
Clones the repository
Installs all dependencies
Sets up 90 bundled skills
Installs Playwright for browser automation
Links the hermes command to your PATH

The full output is about 300 lines. When you see ✓ Installation Complete! you know it worked.

Configuring the LLM Provider

This is where I spent most of Day 2.

Hermes Agent supports many providers: Anthropic, OpenRouter, Google AI Studio, Groq, DeepSeek, and many more. The setup wizard is interactive and well-designed.

I tried several providers:

OpenRouter — ran out of credits immediately (I had an old key with ~1354 tokens left)
Regolo.ai — Italian provider, interesting, but gave 403 errors I couldn't resolve
Gemini free tier — worked, but has a hard limit of 5 requests/minute

What I learned about Gemini free tier: It works, but you need to wait between calls. For interactive development this is manageable. For batch processing, you'd want a paid tier or a different provider.

The setup wizard command is simply:

hermes setup

It walks you through provider selection, API key configuration, and model selection. For Gemini, I selected gemini-2.5-flash — fast, capable, and free.

First Successful Call

After configuration, this command produced a real response:

hermes chat -q "Say hello in one sentence." -Q

Output:

Hello! I am Hermes, a CLI AI Agent.

That single line, after two days of environment struggles, felt like a genuine milestone.

Day 3: Building the Actual Tool

With Hermes Agent working, I built repo-audit-agent — a Python script that wraps Hermes Agent and produces structured technical audit reports.

The core insight is simple: Hermes Agent is not just a chatbot. It uses tools.

When you give Hermes Agent a task that requires browsing the web, it actually opens a browser, navigates to the URL, and reads the content. This is what makes it an agent rather than a language model wrapper.

Here's how I invoke Hermes Agent from Python:

def run_hermes_audit(repo_url: str, max_turns: int = 15) -> str:
    prompt = build_audit_prompt(repo_url, owner, repo_name)

    result = subprocess.run(
        [
            "hermes", "chat",
            "--query", prompt,
            "--quiet",
            "--max-turns", str(max_turns),
        ],
        capture_output=True,
        text=True,
        timeout=300,
    )

    return result.stdout

The --max-turns parameter is important: it controls how many tool-calling iterations Hermes Agent can perform. For a repository audit, 15 turns gives it enough room to browse the repo, read the README, analyze the file structure, and generate the report.

What Hermes Agent Actually Does During an Audit

When I run python3 audit.py https://github.com/NousResearch/hermes-agent, Hermes Agent:

Plans — breaks the audit task into sub-steps autonomously
Browses — navigates to the GitHub repository using its browser tool
Reads — fetches the README, file tree, and visible codebase information
Reasons — synthesizes findings into quality observations and risk assessments
Generates — produces a structured Markdown report following my template

This is genuine agentic behavior. I'm not sending the repository content to a language model — Hermes Agent fetches it itself.

The Output

Here's a real excerpt from a report generated on the Hermes Agent repository:

## Code Quality Score: 7/10

Strong documentation coverage (23.7% comment ratio) and a well-developed 
feature set. Areas for improvement include unknown/duplicate file categories 
and cross-language integration complexity.

## Risk Register (Top 5)

| # | Risk | Severity |
|---|------|----------|
| 1 | Dependency sprawl across 5+ languages | Medium |
| 2 | Documentation drift risk | Medium |
| 3 | Performance bottlenecks in Python core | Medium |
| 4 | Cross-language integration complexity | Medium |
| 5 | Security vulnerabilities in external tools | High |

This is a first-pass review, not a replacement for manual code review. But as a starting point for human analysis, it is genuinely useful.

What I Think About Hermes Agent

After three days of building with it, here are my honest observations:

What Works Well

The installation is excellent. One command, handles everything, works on stock Ubuntu. This is the standard all CLI tools should meet.

The provider ecosystem is broad. If one provider has rate limits or cost issues, you switch to another without changing your code. The hermes setup command handles it cleanly.

Tool use is real. Hermes Agent actually browses, actually reads files, actually executes code. This is not simulated. When you ask it to analyze a repository, it goes and looks at it.

The --quiet flag is a gift. For programmatic use, -Q suppresses all banners and spinners and gives you clean output to parse. This made integration into Python trivial.

90 bundled skills. From GitHub workflows to Jupyter kernels to architecture diagrams — Hermes Agent ships with a large library of task-specific prompts and behaviors. I've only scratched the surface.

What to Watch Out For

Rate limits on free tiers are real. Gemini free tier allows 5 requests/minute. If you're building something that calls Hermes Agent repeatedly, budget for this or use a paid provider.

The browser tool needs resources. Hermes Agent installs Playwright and Chrome for its browser capability. This is about 300MB on disk. Not a problem on EC2, but worth knowing if disk space is tight.

The terminal inside Colab/browser environments has character encoding issues. I encountered escape sequences (^[]11;rgb:0000/0000/0000) corrupting commands when copy-pasting into browser-based terminals. Run Hermes Agent on a real SSH session or local terminal when possible.

The Bigger Picture

Hermes Agent is interesting not because of what it does today, but because of what it represents.

A lot of AI tooling today seems to fall into one of two categories: proprietary cloud services where you send your data and trust a vendor, or lightweight local wrappers that are really just API clients with a nicer interface.

Hermes Agent is neither. It is an open-source agent runtime that you deploy on your own infrastructure, configure with your choice of LLM provider, and extend with skills you write yourself. The agent logic — planning, tool use, multi-step reasoning — runs on your machine.

Of course, the configured LLM provider still receives the prompts and relevant context, so provider choice and data handling policies still matter.

For developers building on sensitive data (mine includes Italian public-sector procurement documents), this distinction matters.

Getting Started

If you want to try Hermes Agent yourself:

# Install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Configure (interactive wizard)
hermes setup

# First test
hermes chat -q "What files are in my current directory?" -Q

For a cloud environment without local Linux, AWS EC2 t2.micro free tier is the fastest path to a working setup.

The Hermes Agent documentation is thorough and the GitHub repository is active.

Try the Project

If you want to see Hermes Agent doing real work on a real codebase, try repo-audit-agent:

git clone https://github.com/MaurizioLisanti/repo-audit-agent
cd repo-audit-agent
python3 audit.py https://github.com/NousResearch/hermes-agent

It uses Hermes Agent to perform first-pass technical reviews of any public GitHub repository and saves the report as a Markdown file.

Built during the Hermes Agent Challenge 2026. The environment struggles were real. The deadline was real. The tool works.

Repo-audit-agent — AI-powered GitHub repository auditor built with Hermes Agent

MLisanti_Dev — Fri, 29 May 2026 22:29:31 +0000

This is a submission for the Hermes Agent Challenge: Build With Hermes Agent

What I Built

repo-audit-agent helps developers perform fast first-pass repository reviews using Hermes Agent.

Point it at a public GitHub repository and Hermes Agent performs a first-pass review of the visible repository content, then generates a structured Markdown report with tech stack detection, code quality observations, a risk register, and an improvement roadmap.

A faster starting point for human review. No copy-pasting code into a chat window. Just one command:

python3 audit.py https://github.com/NousResearch/hermes-agent

And Hermes Agent does the rest.

The Problem It Solves

Every developer knows the situation: you inherit a codebase, evaluate an open source dependency, or onboard a new project. Before you can do anything useful, you need a quick technical assessment — what's the stack, what are the risks, what needs fixing first.

Traditionally this takes hours. With repo-audit-agent and Hermes Agent, it takes minutes.

Sample Output

Here's a real report generated by Hermes Agent on the hermes-agent repository itself:

# Technical Audit Report: NousResearch/hermes-agent

Generated: 2026-05-29 21:07 UTC
Tool: repo-audit-agent v1.0.0 powered by Hermes Agent

## Executive Summary

The hermes-agent repository is a substantial, well-structured project 
primarily developed in Python with significant TypeScript contributions, 
indicating a complex application with a web-based interface...

## Tech Stack

- Primary: Python 46.7%, TypeScript 7.9%, TSX 2.0%
- Config: YAML, TOML, JSON, Docker
- Infrastructure: Bash, Systemd, Makefile

## Code Quality Score: 7/10

Strong documentation coverage (23.7% comment ratio) and a well-developed 
feature set. Areas for improvement include unknown/duplicate file categories 
and cross-language integration complexity.

## Risk Register (Top 5)

| # | Risk | Severity |
|---|------|----------|
| 1 | Dependency sprawl across 5+ languages | Medium |
| 2 | Documentation drift risk | Medium |
| 3 | Performance bottlenecks in Python core | Medium |
| 4 | Cross-language integration complexity | Medium |
| 5 | Security vulnerabilities in external tools | High |

## Improvement Roadmap (Top 5)

1. Automated dependency scanning across all ecosystems
2. Performance profiling for critical Python components
3. Refactor unknown/duplicate file categories
4. Comprehensive E2E testing across frontend and backend
5. Streamline CI/CD pipeline and build process

Real output from a real repository, generated by Hermes Agent and intended as a starting point for human technical review.

Demo

Running an Audit

# Install Hermes Agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Configure your LLM (Gemini free tier works great)
hermes setup  # Select Google AI Studio

# Clone and run
git clone https://github.com/MaurizioLisanti/repo-audit-agent
cd repo-audit-agent
python3 audit.py https://github.com/NousResearch/hermes-agent

What Happens Under the Hood

When you run audit.py, Hermes Agent:

Receives a detailed audit prompt with the target repository URL
Plans its analysis strategy autonomously
Uses its browser tool to navigate to the GitHub repository
Fetches the README, file structure, and codebase information
Reasons about code quality, risks, and improvement priorities
Generates a structured Markdown report

The report is saved to ./reports/audit_<repo>_<timestamp>.md.

Architecture

repo-audit-agent
│
├── audit.py                  ← CLI entry point
│   ├── build_audit_prompt()  ← Instructs Hermes Agent
│   ├── run_hermes_audit()    ← Invokes Hermes Agent
│   └── save_report()         ← Saves Markdown report
│
└── reports/                  ← Generated audit reports

Code

GitHub Repository: https://github.com/MaurizioLisanti/repo-audit-agent

The core of the tool is how it communicates with Hermes Agent:

def run_hermes_audit(repo_url: str, max_turns: int = 15) -> str:
    """
    Invoke Hermes Agent to perform the repository audit.

    Hermes Agent uses its agentic capabilities (web browsing, tool use,
    multi-step reasoning) to fetch and analyze the repository.
    """
    prompt = build_audit_prompt(repo_url, owner, repo_name)

    result = subprocess.run(
        [
            "hermes", "chat",
            "--query", prompt,
            "--quiet",
            "--max-turns", str(max_turns),
        ],
        capture_output=True,
        text=True,
        timeout=300,
    )

    return result.stdout

The key insight: Hermes Agent's --max-turns parameter controls how many tool-calling iterations it can use. For large repositories, increasing this gives Hermes Agent more room to explore and analyze.

My Tech Stack

Hermes Agent — core agentic engine (planning, tool use, reasoning)
Python 3.11 — CLI wrapper and report handling
Google Gemini 2.5 Flash — LLM provider via Hermes Agent
AWS EC2 — Ubuntu server on a t2.micro free-tier instance
GitHub — repository hosting and output

How I Used Hermes Agent

Hermes Agent is not a wrapper around this tool — it IS the tool.

Agentic Capabilities Used

1. Multi-step Planning
When given the audit prompt, Hermes Agent doesn't just send one API call. It breaks the task into sub-steps: fetch the repository, read the README, analyze the file structure, identify the tech stack, assess quality, generate the report. This planning happens autonomously.

2. Tool Use — Web Browsing
Hermes Agent uses its built-in browser tool to navigate to the GitHub repository URL and fetch real content. It reads the actual repository structure, not a cached or synthetic version.

3. Multi-step Reasoning
Hermes Agent synthesizes what it finds — file counts, language percentages, documentation coverage — into a coherent technical assessment with a justified quality score and prioritized recommendations.

4. Structured Output Generation
The prompt instructs Hermes Agent to produce output in a specific Markdown structure. Hermes Agent follows the template reliably, making the output machine-readable and consistent across different repositories.

Why Hermes Agent Was the Right Fit

I chose Hermes Agent for three reasons:

Open source and self-hosted agent runtime: I run Hermes Agent on my own AWS EC2 instance, while LLM calls are routed through the configured provider. In this demo I used Google Gemini via Hermes Agent.
Real tool use: Hermes Agent actually browses the repository. This is not a prompt that asks a language model to "imagine" analyzing a repo — Hermes fetches real data.
Composable: The hermes chat -q interface makes it trivial to integrate Hermes Agent into any Python script or pipeline.

Real-World Application

I built this tool for a real need: I maintain several Italian public-sector repositories (fatturapa-mcp-server, sdi-ops-monitor, conto-termico-gse, GaraAI) and needed a fast way to audit their technical health before client presentations.

repo-audit-agent + Hermes Agent gives me a structured first-pass technical review in minutes, which I can then validate and refine manually.

Limitations

repo-audit-agent generates AI-assisted first-pass technical reviews. It does not replace manual code review, security testing, dependency scanning, or production readiness assessment. The generated findings should be validated by a human engineer before being used for business or security decisions.

Repository: https://github.com/MaurizioLisanti/repo-audit-agent

Built with Hermes Agent by Nous Research

Hello from Italy

MLisanti_Dev — Tue, 19 May 2026 11:34:30 +0000

Hi DEV community! 👋

I'm Maurizio, a Backend Engineer from Italy specializing in agentic AI systems applied to Italian institutional domains.

What I build:
🔹 fatturapa-mcp-server — open source MCP server for Italian e-invoicing, live on PyPI

🔹 sdi-ops-monitor — AWS operational dashboard for SDI/FatturaPA flows

🔹 GaraAI — multi-agent pipeline for Italian public tenders

🔹 conto-termico-gse — agentic RAG on Italian energy regulations

My stack: Python · PHP · AWS · MCP · LangGraph · Weaviate

Founder of Linux PropLUG — Italian community connecting Linux and
Open Source with PropTech.

Anthropic Certified — MCP Advanced Topics.

Looking forward to connecting
with the community here! 🚀

hello, python, ai, beginners