Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hermes-prime-mcp load the conventions card for this repo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Deliver a versioned convention card to a fresh Claude Code session.
hermes-prime is developed by Hermes Labs.
Hermes Labs is an agentic infrastructure company building the reliability layer for autonomous systems.
The Bash surface snapshots the card into a project's CLAUDE.md; the read-only MCP
surface returns the same card over stdio. The mechanism makes conventions
available. It does not prove that a model will follow them or prevent drift.
This is a small transport, not an enforcement layer. Hermes Labs ships the
convention card it uses itself; fork it or select another fragment with
HERMES_SESSION_INIT_FRAGMENT=/path/to/custom.md.
Two surfaces share one fragment: a four-subcommand Bash tool for
CLAUDE.md-based workflows and a Claude-Code-native MCP server that does not
mutate CLAUDE.md. Neither surface calls a model or a network service. The Bash
path makes no global configuration change; MCP registration uses the scope the
user selects.
Conventions can fall out of visible context between sessions. A versioned card gives a new session one concrete artifact to read instead of requiring it to reconstruct those conventions from scattered notes.
The discipline rules normally live in scattered handbook docs, feedback files, or session-end retros — places a fresh session never reads. hermes-prime packages them as a single self-contained card the orchestrator opens with.
Related MCP server: Context Grove
Most "set up the agent" tools either (a) ship a giant prompt file you copy-paste,
or (b) install a global hook that runs on every session whether you want it or
not. hermes-prime is per-project, marker-anchored, and idempotent. Unedited
injected suffixes are byte-reversible; edited blocks use the documented
marker/backup fallback.
The fragment is a snapshot, not a live reference. Re-inject to refresh. The marker (<!-- session-init: BEGIN/END -->) means uninject is byte-clean.
Surface | Audience | Mechanism |
MCP server (recommended for Claude Code) | Claude Code users | Native MCP tools — |
Bash binary ( | Claude Code and other workflows that explicitly read a project's | Inject the fragment into |
Both share the same CLAUDE-fragment.md. They are independent surfaces; pick whichever fits your agent.
claude mcp add --scope local hermes-prime -- python3 "$PWD/mcp-server/hermes_prime_mcp.py"Run that command from the repository root. Local scope loads the server for the
current project. Last verified against Claude Code 2.1.268 on 2026-09-11:
claude mcp list reports the server as Connected. The server's initialize
response carries a short instructions string, which Claude Code shows to the
model so a fresh session knows to call get_conventions. Use --scope user only if you intend to make the same command
available to your own sessions across projects. Then call get_conventions
from a session covered by the selected scope. Pure stdlib, no third-party
runtime dependencies. Full registration and removal instructions, plus the
packaged pip install hermes-prime-mcp console-script path and the
server.json MCP Registry manifest, are documented in
mcp-server/README.md.
git clone https://github.com/hermes-labs-ai/hermes-prime.git
cd hermes-prime
ln -s "$PWD/bin/hermes-session-init" /usr/local/bin/hermes-session-init
hermes-session-init --checkOr symlink into ~/bin/. No package install — it is one bash script and one markdown fragment.
# Require the fragment; report optional companion tools as information
hermes-session-init --check
# Print the fragment to stdout (pipe-friendly)
hermes-session-init --print
# Inject the fragment into a project's CLAUDE.md (idempotent, backs up existing)
hermes-session-init --inject ~/Documents/projects/some-project
# Remove the fragment cleanly (anchored on the marker)
hermes-session-init --uninject ~/Documents/projects/some-projectSubcommand | Behavior | Exit |
| Requires only the fragment file. Reports hermes-ground, hermes-rubric-blinded, and the handbook as optional informational companions. | 0 fragment present / 1 fragment missing |
| Prints the CLAUDE-fragment to stdout. Useful for piping into | 0 |
| Appends the fragment to | 0 |
| Removes the exact suffix added by | 0 ok / 1 not-found |
Note:
hermes-groundis an internal Hermes Labs grounding tool. It is not publicly released; the convention simply describes the orchestrator behavior it triggers.
A short markdown block containing:
Grounding triggers — the 7 conditions under which the orchestrator should call hermes-ground for an external reality check.
Self-contained conventions — calibration, rubric pass-through, grounding, and name discipline.
Tool map — functional categories, Hermes Labs implementations, and manual fallbacks.
The rule most often forgotten mid-session — no noun-phrase label until a file exists at a path.
See CLAUDE-fragment.md for the full text. The fragment is the contract.
Three honest evals live in evals/:
E1 — convention-recall test: does a fresh claude --print session injected with the fragment correctly identify hermes-ground as the external-grounding tool, vs an un-injected session?
E2 — idempotency stress: inject 5x in a row, assert size delta ≤ 2 chars.
E3 — uninject roundtrip: inject → uninject → require identical raw pre/post hashes.
Run them: bash evals/preliminary-bootstrap-eval.sh. Protocol in evals/EVAL-PROTOCOL.md. Run transcripts at evals/runs/. Null results published unredacted per the standing convention.
hermes-prime is a convention-delivery surface among the Hermes Labs open-source
tools. It does not replace companion tools and does not ensure that they are
called.
hermes-rubric — evidence-first scoring; the convention "every shippable artifact passes through a BLINDed rubric" points here.
hermes-blind — a separately invoked multi-turn recovery scaffold.
Source version 0.2.1-alpha.1 — unreleased alpha candidate. There is no public 0.2.1-alpha.1 tag or GitHub release, and this branch does not authorize one.
The MCP distribution is a separate surface and it is public: hermes-prime-mcp
0.2.1a2 is on PyPI and the MCP Registry listing
io.github.hermes-labs-ai/hermes-prime 0.2.1-alpha.1 is active (both
verified 2026-09-18). uvx --from hermes-prime-mcp hermes-prime-mcp works today
without a checkout. "Unreleased" above describes the repository, not the package.
The mechanism suite contains 11 Bash assertions plus 13 MCP tests. E1 is one author-run three-question control/treatment observation; it is preliminary convention-recall evidence, not evidence that the tool prevents drift or improves downstream task performance.
If E1 returns a null result on a larger sweep, that gets published, not papered over. Same standing convention as the rest of the Hermes Labs open-source tools.
Before requesting any push or release, run the local mechanism gate:
./scripts/local-ci.shIt runs ShellCheck, the 11-assertion Bash suite, the 13-test MCP suite, and
fragment size/marker checks. The hosted workflow (.github/workflows/ci.yml)
runs the same suites on macOS and Ubuntu. Exit 0 is evidence only for those named checks at the
current tree; it is not push, release, or publication authorization.
MIT. See LICENSE.
Built by Hermes Labs.
Hermes Labs is an agentic infrastructure company building the reliability layer for autonomous systems. This repository is one small mechanism in that portfolio; its claims are limited to behavior exercised by the checks above.
For enterprise deployments and AI-reliability engagements: roli@hermes-labs.ai · hermes-labs.ai
On naming. Hermes Labs is named for Hermes, the Greek messenger god — patron of communication and interpretation, the herald who carries meaning between worlds. The thread to the work: hermeneutics, the theory of interpretation that takes its name from Hermes, is the philosophical anchor for an agentic infrastructure company whose substrate is linguistic. Not affiliated with NousResearch's Hermes LLM line or their hermes-agent framework — different companies, different work.
Founder: Rolando (Roli) Bosch. Site: hermes-labs.ai Citation: Bosch, R. (2026). Hermes Labs: AI reliability engineering for production agents and LLM applications. https://hermes-labs.ai
Return the hermes-prime CLAUDE-fragment as raw markdown — the session-priming conventions (grounding triggers, tool map, rules-most-often-forgotten). Optional scope_class returns a scoped fragment from fragments/<scope_class>.md when present; otherwise falls back to the default fragment. Call once at session start to load conventions without polluting CLAUDE.md.
| Name | Required | Description | Default |
|---|---|---|---|
| scope_class | No | Optional scope class (e.g. 'session-init'). Falls back to the default fragment if unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does well: it discloses the fallback behavior for unknown scopes, the file lookup pattern (fragments/<scope_class>.md), the return format (raw markdown), and the practical benefit (no CLAUDE.md pollution). It stops short of stating error behavior if the default fragment is also absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences covering purpose, behavior, and the call-site trigger with essentially no filler. Slightly dense with internal jargon (hermes-prime, CLAUDE-fragment) but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A single optional parameter with no output schema is well covered: the description explains what comes back (raw markdown fragment) and the fallback path. Absent output schema, the return-value explanation is adequate though brief.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents scope_class including the fallback rule, so the description's scoped-file detail largely restates it. It adds the concrete path convention but no examples of valid classes beyond what the schema gives.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the hermes-prime CLAUDE-fragment as raw markdown') and enumerates the content it contains (grounding triggers, tool map, rules). It never names the sibling list_scopes, so the boundary between the two is left implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call once at session start to load conventions without polluting CLAUDE.md' gives a clear trigger and rationale for use. It does not explicitly say when not to use it or point to list_scopes as the way to discover valid scope_class values, which leaves a small inference gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available scoped fragments (one per line). Always includes 'default'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden; it does disclose the useful guarantee that 'default' is always present and that output is one entry per line. It does not explicitly state that it is a read-only operation or whether results are ordered or filtered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the resource and output format front-loaded. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool with no output schema, naming the return format and the guaranteed 'default' entry is nearly everything an agent needs. Only the relationship to get_conventions is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The description's only parameter-adjacent detail, the always-present 'default' entry, is a return-value note rather than an input note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('scoped fragments'), plus the output shape ('one per line'), so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling get_conventions by saying what a 'scoped fragment' is or how it differs from conventions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus get_conventions, and no prerequisites or exclusions. The sibling relationship is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_conventionslist_scopesScored across 2 tools
get_conventions retrieves content while list_scopes enumerates available fragment names; the two purposes are clearly disjoint and cannot be confused. Descriptions reinforce the distinction (one returns markdown, the other a list of names).
Both tools follow a consistent verb_noun snake_case pattern (get_conventions, list_scopes). The verbs also match expected semantics — 'get' for retrieval of content, 'list' for enumeration.
Only two tools, which sits at the thin end of the rubric's acceptable range. The domain is narrow (loading convention fragments), so two tools are defensible, but the surface feels minimal even for that scope.
The read-only retrieval lifecycle is essentially covered: discover scopes, then fetch a fragment (default or scoped) in one call. Minor gaps exist around verifying fragment freshness or version, but agents can work around them by re-calling get_conventions.
Read-only catalog of prompt packs and rule files: Cursor, CLAUDE.md, AGENTS.md, SKILL.md.
Search verified Claude Code plugins and skills; fetch portable SKILL.md sources. Read-only.
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
