Hermes Agent
Hermes is the messenger — a terminal AI agent built around the idea that the hardest part of agentic coding isn't generating code, it's understanding what to generate and why. It takes a thoughtful, step-by-step approach to tasks: read the codebase, understand the architecture, plan the changes, then execute. Not the fastest tool in the drawer, but arguably the most reliable.
It's a project-scoped AI agent. You initialize it in your repo with hermes init, configure your model preference, and it creates a context file that helps it understand your project. From there, every task starts with codebase analysis — Hermes reads relevant files, understands relationships, and builds a mental model before writing a single line of code.
The dry-run habit is the most important thing to internalize early. Hermes is designed to show you what it plans to do before it does it. By default, changes are proposed, not applied. You review the plan, you approve it, then it executes. This deliberate approach means fewer "oh no what did it do" moments and more "yeah that's exactly what I wanted" outcomes.
Model flexibility is a first-class feature. Hermes works with Anthropic Claude, OpenAI, or any OpenAI-compatible API endpoint. Running local models? Point it at your Ollama instance. Want to use a specific fine-tuned model? Just configure the endpoint. The agent doesn't care what's generating the responses — it just needs something smart enough to follow its workflow.
The task decomposition is where Hermes differentiates. Complex tasks get broken into sub-tasks with clear dependencies. "Refactor the auth system" becomes: (1) map all auth-related files, (2) identify the current pattern, (3) propose the new pattern, (4) update core auth module, (5) update dependent modules, (6) add/update tests. Each step is visible and reviewable.
Project memory is persistent across sessions. Hermes maintains a memory file in your project that captures architectural decisions, coding patterns, and lessons learned from previous tasks. This means the second task in a project benefits from everything it learned doing the first task. The hundredth task has accumulated real understanding of your codebase.
The review mode is perfect for code review tasks. Feed it a PR diff, and Hermes analyzes the changes in context — checking for bugs, suggesting improvements, verifying test coverage, and flagging potential issues. It's like having a thorough senior engineer review every PR, except it doesn't get tired, doesn't miss things because it's reviewing its tenth PR of the day.
Error recovery is thoughtful. When something goes wrong — a test fails, a build breaks, a lint rule is violated — Hermes doesn't just retry blindly. It reads the error, understands what went wrong, adjusts its approach, and tries again. This iterative debugging loop is where you really see the value of the "understand first, act second" philosophy.
The documentation-first approach means Hermes is good at explaining what it's doing and why. Every change comes with context about the reasoning behind it. This isn't just nice for understanding — it's essential for trust. When an AI agent is making autonomous changes to your codebase, being able to understand its reasoning is the difference between trusting the process and babysitting the output.
Who's it for? Engineers who want a reliable, predictable AI agent they can trust with real tasks. Teams doing careful, methodical development where quality matters more than speed. Anyone who's been burned by aggressive AI tools that made messes they had to clean up. If you'd rather have an agent that takes an extra minute but gets it right the first time — Hermes is built for that.
Power Tips
Task descriptions, plans, checkpointsQuick Wins
Without hermes.config.json, Hermes uses defaults that probably don't match your stack. The init wizard takes 2 minutes and makes every subsequent task dramatically more accurate.
Hermes is autonomous. See the full plan before any files are touched. This is especially important for refactors, migrations, and anything involving multiple files.
Vague: "improve auth." Specific: "Add rate limiting to POST /api/auth/login — max 5 requests per minute per IP, return 429 with Retry-After header." Specificity is everything.
Hermes logs every step of its execution. When a task doesn't go as expected, the log tells you exactly what happened and where it diverged from the plan.
For long-running operations, checkpoint at meaningful milestones. If something goes wrong later, you can resume from the checkpoint instead of starting over.
Use a cheaper model for exploration and planning tasks, a smarter one for actual implementation. You're not locked into one model for the whole workflow.
Hidden Features
Write a .hermes/workflow.yaml that describes a multi-step process. Hermes executes it deterministically every time — great for deployment pipelines, onboarding scripts, and anything you'd otherwise document as a manual runbook.
Hermes has a plugin system for tools. Add plugins for your database CLI, cloud provider, test framework, or any other tool you use. Hermes can then invoke them directly as part of its execution plans.
Long tasks get interrupted — network drops, rate limits, system sleep. Checkpoints let Hermes resume exactly where it left off without re-running everything from the start.
hermes resume --checkpoint latest Common Mistakes
Hermes is autonomous and will make real changes immediately. Running without --dry-run on a task you haven't validated means you're discovering the plan by watching it execute.
Always --dry-run on any task that modifies files. No exceptions until you know the tool well.Vague input = vague plan = vague output. Hermes is only as good as the task description you give it. Ambiguous tasks produce generic results.
Include: what to change, where (file/function), the expected behaviour, and any constraints.A 15-minute task that gets interrupted at minute 12 has to start over. That's avoidable.
Run hermes checkpoint at logical milestones during long operations.