hermes-max
An open suite of MCP servers that gives coding agents, including those running on local or low-cost models, the
engineering tools frontier agents rely on: a verification gate, repository map, language-server navigation, code
graph, retrieval and knowledge graph, deep research, checkpoints, watchdogs and validated edits. It adds a
planner/executor topology in which a capable model plans and a cheaper or local model executes.
Note
hermes-max was built and piloted with Hermes Agent as the host.
The MCP servers are independent processes and can be used by other MCP clients; only Hermes Agent has been
tested end to end (see Client compatibility). No benchmark results are published yet.
Why
Coding agents built on small or local models fail in predictable ways: they lose track of large repositories, edit
files they have not read, declare work done without running tests, and loop when stuck. Frontier agents compensate
with tooling as much as with model capability. hermes-max packages that tooling as MCP servers so any agent can use
it, and makes completion depend on deterministic checks rather than on the model's own report.
What's inside
Eighteen servers, each an independent process with its own health check; stopping one removes one capability and
does not crash the agent. The list is defined in mcp-manifest.yaml.
| capability |
server |
what it provides |
| Verification |
mcp-verify |
lint → typecheck → tests as the completion gate; property, metamorphic, differential and mutation testing; bounded formal checks (Kani) where applicable |
| Edits |
mcp-edit |
whole-file and diff edits that reject elisions and malformed patches before they reach disk |
| Repository map |
mcp-repomap, mcp-scopemap |
tree-sitter symbol graph ranked with PageRank (after Aider's repository map); a two-phase static context map for large repositories |
| Code intelligence |
mcp-lsp |
definitions, references, hover, rename and diagnostics through Serena; falls back to text search |
| Code graph |
mcp-codegraph |
callers and callees, importers, change impact, dead code, structural search (ast-grep) |
| Retrieval |
mcp-codebase-rag |
hybrid BM25, dense and graph retrieval over code and documents; degrades to BM25 plus graph without embedding models |
| Memory |
mcp-knowledge-graph |
SQLite entity and relation store with self-editing core memory |
| Research |
mcp-docs, mcp-research |
self-hosted web search (SearXNG) and clean fetch; a bounded research loop that requires two sources per claim, with keyless academic and code-search sources |
| Long-horizon reliability |
mcp-checkpoint, mcp-watchdog |
checkpoints taken only from a verified state, with revert-to-last-green; out-of-band loop, stall and budget detection |
| Best-of-N |
mcp-search |
parallel drafts with the verifier, not a model, selecting the result |
| Planning and routing |
mcp-escalation, mcp-router |
the conductor: difficulty classification, presence-gated escalation to stronger models, optional multi-model planning committees |
| Cost and observability |
mcp-costprofiler, mcp-observability |
append-only cost ledger with per-run caps; traces and trajectories exported over OpenTelemetry to a local collector |
| Supply chain |
mcp-security |
package checks against OSV advisories (fails closed on known malware) and egress guards |
Server reference: docs/mcp-servers.md.
How it fits together
flowchart LR
A[Coding agent<br/>MCP client] -->|MCP| S[hermes-max servers<br/>verify · edit · repomap · lsp · codegraph<br/>rag · kg · research · checkpoint · watchdog]
S --> F[inference fabric<br/>roles → providers]
F --> P[planner role<br/>stronger model]
F --> E[executor role<br/>cheaper or local model]
F --> R[research and synthesis roles]
S --> T[deterministic tools<br/>linters · type checkers · tests · LSP · tree-sitter]
Loading
Servers request a role (planning, execution, research, synthesis, escalation) rather than a model. The inference
fabric resolves each role to the first configured provider whose credentials are present; absent providers are
skipped. With only a local endpoint configured, everything runs locally.
Models and providers
hermes-max works with any OpenAI-compatible endpoint: local inference (vLLM, llama.cpp, MLX, Ollama) and hosted APIs.
Roles are mapped to providers in configuration, not code (roles.yaml for role chains, inference.yaml for
provider slots, modes.yaml for named presets):
# roles.yaml (abridged; see config/roles.example.yaml). Each role is an ordered chain of provider.slot
# entries defined in inference.yaml; the first entry whose credentials are present is used.
roles:
code_plan: # once per task; the dominant quality lever
- hosted.planner
- local.driver
code_execute: # high-volume turns implementing the plan
- local.driver
- hosted.driver
code_steer: # a nudge when the executor stalls or verification fails
- hosted.fast
The specific providers and models the project was piloted with, with prices, limits and verification dates, are in
docs/providers.md; keeping model identifiers current is described in
docs/roster.md. Provider terms and free tiers change frequently and are not part of this README.
Quickstart
Requirements: Python 3.10+, the Hermes Agent on PATH, and at least
one model endpoint (local or hosted). Docker is optional (SearXNG, Crawl4AI, Phoenix).
git clone https://github.com/patrickbdevaney/hermes-max && cd hermes-max
./install.sh # idempotent: virtual environments, configuration, MCP registration
cp .env.example .env # add the endpoints and keys you intend to use
hm up --free # start everything; --free = local executor, --full = hosted executor (docs/modes.md)
hermes # launch the agent
hm status shows running servers, the active mode and spend; hm down stops everything. Annotated walkthrough:
QUICKSTART.md. Modes and profiles: docs/modes.md, docs/profiles.md.
Client compatibility
| client |
status |
| Hermes Agent |
tested (primary host; memory and skills integration are Hermes-specific) |
| Claude Code, Codex CLI, OpenCode, Gemini CLI / Antigravity, Cursor, VS Code, Zed |
untested; servers use standard MCP over HTTP and are expected to register as remote servers |
Evidence
No benchmark results are published yet. The intended measurement is an ablation: the same model and agent harness
with and without the suite, on SWE-bench Pro and Terminal-Bench 2.0, reported with date, harness, model, run count and
confidence interval. The evaluation integration is described in docs/eval-integration.md.
Security
- Binding. Servers listen on
127.0.0.1 by default (MCP_BIND_HOST); they are not intended to be exposed to a
network. Use a token or a unix socket if you change this.
- Execution.
mcp-verify runs your project's linters, type checkers and tests, and the research servers fetch
web content. Neither is a security sandbox: run untrusted repositories in a container or virtual machine.
- Prompt injection. Fetched web content and repository text can contain instructions. Treat model output that
results from them as untrusted; completion still requires the deterministic verification gate.
- Outbound data. Prompts and code context are sent to the hosted providers you configure, under their terms.
With only local endpoints configured, no model traffic leaves the machine.
- Supply chain.
mcp-security checks packages against OSV advisories before installation.
Telemetry
None is sent to the project. Traces and metrics are emitted over OpenTelemetry to a local collector (Phoenix,
localhost:4317 by default) only if you run one; otherwise they are dropped.
Documentation
Build specifications that produced this system are kept for provenance in archive/specs/.
Acknowledgements
hermes-max builds on Hermes Agent (Nous Research), the repository-map
approach of Aider, Serena,
tree-sitter, ast-grep,
SearXNG, Crawl4AI,
Arize Phoenix, Kani and the
OSV advisory database. Mention does not imply endorsement.
License
MIT. See LICENSE. Third-party tools, servers and model providers keep their own licenses and terms.