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

topic	document
Architecture and configuration model	docs/architecture.md
Piloted provider stack, costs and limits	docs/providers.md, docs/cost.md
Local hardware and deployment	docs/hardware.md, docs/deployment.md
Long-horizon operation	docs/long-horizon.md
Research engine	docs/research-engine.md
Skills	docs/skills.md
Troubleshooting	docs/troubleshooting.md

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.