Adapter#
An adapter is a directory of source files governed by its template’s metadata in .hermit/. The Trainer stores
versions of those files in Git. The acting integration turns their exports into host instructions, skills, roles, and callable tools.
There are two file paths to understand: deployment creates files for the acting host; evolution edits a working copy of the adapter sources.
The adapter structure#
The complete example in docs/_examples/file_adapter/ contains:
file_adapter/
.hermit/
adapter.yaml required: template identity and specification
EVOLVER.md template guide for the learner
exports.yaml optional: what the acting agent receives
ADAPTER.md optional: context for the acting agent
agents/reviewer.md optional: one file per subagent
skills/verify-output/
SKILL.md optional: one skill
tools.py optional: tool implementations (the tool list is in exports.yaml)
README.md usage and dependencies
Every adapter has .hermit/adapter.yaml (its sections and rules: adapter metadata reference).
ADAPTER.md is a fixed name and is always exported as the acting agent’s context; without it the context is empty.
exports.yaml declares the other exports; without it the adapter exports its context only, and its context key may
be omitted. .hermit/EVOLVER.md is learner guidance; it is not inserted into the acting agent’s context. tools.py is a convention:
each tool’s entrypoint names its file and function.
A subagent is one Markdown file, in the same format as Claude Code’s subagent files: YAML frontmatter with name
and description, and the body as its instructions.
---
name: reviewer
description: Check a result against the task requirements.
---
Check whether the result meets the stated requirements. Explain any mismatch.
These declarations connect the subagent and skill directories to the loader:
agents: agents
skills: skills
What an adapter can rely on#
Two things hold for every adapter, whatever the template, the learner or the acting agent:
.hermit/is fixed. It holds the template’s metadata and the learner’s guide; a learner cannot change it (the check restores it from the template root), and it never reaches the acting agent.ADAPTER.mdreaches the acting agent as its instructions at the start of every task. The built-in agents and the hosts do this; a task’s own acting agent must do it too.
Both hold wherever the adapter is used. Where that can be is the template’s call: a template that sets
plugin-portable: false keeps its adapters inside hermit runs, and hermit deploy and hermit convert refuse them.
Everything else depends on the acting agent: the hosts and the built-in agents deliver what exports.yaml
declares, a task’s own agent may deliver more or less. A learner’s guide that needs more than these two facts says
where the rest is described.
Acting interface#
Which files are written into the host?#
A deployment writes into a separate host workspace in two parts. The whole adapter, every file but .hermit/,
.git/ and what exports.yaml marks internal, is copied as it is to
hermit/<adapter id>/, and the context block tells the agent so: “This adapter’s files are in hermit/<adapter id>/. Paths in the instructions below, and in the adapter’s skills and roles, are relative to that folder: run a
command they give from there.” Then each export exports.yaml declares is
connected to the host’s own place when the host has one, so that the host loads it; an export the host has no place
for stays a file of the copy, and the context names it with what to do with it. The rule is the same for every
host, and for the built-in codex, claude-code, pi, mini-swe-agent, opencode, dsh and hermes acting agents, which deploy as hermit deploy does: an adapter
is deployed as far as the host can take it, and nothing it holds is out of the agent’s reach.
Adapter source |
Deployment operation |
Codex output |
Claude Code output |
Pi output |
mini-swe-agent output |
OpenCode output |
DeepSeek Harness output |
Hermes Agent output |
|---|---|---|---|---|---|---|---|---|
Every file but |
Copy it as it is. |
|
|
|
|
|
|
|
|
Insert the line above and its text into a managed instruction block. |
|
|
|
the system template of |
|
|
|
|
Copy the skill directory. |
|
|
|
named in the system template (mini-swe-agent loads no skills): name, description, the path of its |
|
|
|
|
Convert the subagent into native host files: frontmatter gives name and description, the body becomes its instructions. |
|
|
named in |
named in the system template (no subagents) |
named in |
named in |
named in |
|
Configure a framework MCP server that loads the source adapter. |
|
|
|
|
|
|
|
a hooks file, through |
Write the hooks the host runs, each command run from |
|
|
named in |
named in the system template (mini-swe-agent runs no hooks) |
named in |
named in |
named in |
every other file of the copy |
Name it, with its frontmatter description or first line, under “Adapter resources” in the context (up to 60 files; the rest are counted). |
|
|
|
the system template |
|
|
|
This is how the adapter reaches the acting system. The host reads the generated instruction, skill, role and hook
files; tool configuration makes the declared tools available through its tool interface. What the adapter does not
declare, or the host cannot load, reaches the agent as files under hermit/<id>/, which the context names. An
export placed as files keeps its information but not its mechanism (a hook named in the context runs only if the
agent runs it), and the deployment record (.hermit-deploy.json, placed) says which exports went where. The
context must fit what the host reads: Codex reads AGENTS.md up to its project_doc_max_bytes (32 KiB unless set)
and drops the rest without a word, so the Codex deployment refuses a longer AGENTS.md (hermit deploy --context-limit, the acting agent’s project_doc_max_bytes). DeepSeek Harness gives the model at most 65,536 bytes
of a project’s instructions and cuts the rest, so its deployment refuses an AGENTS.md that would not fit.
Hermes Agent reads one project context file, the first it finds of .hermes.md (also searched up to the repository’s
root), AGENTS.md, CLAUDE.md and .cursorrules, so its deployment writes .hermes.md; Hermes cuts a context file
past a share of the model’s context window unless context_file_max_chars is larger, which the deployment’s config
part sets (1,000,000).
A hook runs in the
directory the session started in, so the deployment prefixes each command with cd hermit/<id> (its absolute path):
a hook finds the files it names where it found them in training. Interactive Codex asks the user to trust the
project’s hooks before they run, and codex exec skips hooks nobody trusted, so the built-in Codex agent passes
--dangerously-bypass-hook-trust when its task’s deployment wrote hooks; claude -p runs a project’s hooks as they
are.
For the example above, the generated workspaces contain:
codex-workspace/
AGENTS.md
hermit/file-example/
ADAPTER.md exports.yaml tools.py agents/ skills/ README.md
.codex/
config.toml
agents/reviewer.toml
skills/verify-output/SKILL.md
.hermit-deploy.json
claude-workspace/
CLAUDE.md
hermit/file-example/
ADAPTER.md exports.yaml tools.py agents/ skills/ README.md
.mcp.json
.claude/
agents/reviewer.md
skills/verify-output/SKILL.md
.hermit-deploy.json
pi-workspace/ # only for an adapter without roles
AGENTS.md
hermit/file-example/
ADAPTER.md exports.yaml tools.py skills/ README.md
.pi/
mcp.json
skills/verify-output/SKILL.md
.hermit-deploy.json
mini-swe-agent-workspace/
mini-swe-agent.yaml # the context, the resources and the tools in its system template
hermit/file-example/
ADAPTER.md exports.yaml tools.py skills/ agents/ README.md
.hermit-deploy.json
opencode-workspace/ # roles stay files under hermit/<id>/, named in AGENTS.md
AGENTS.md
opencode.json
hermit/file-example/
ADAPTER.md exports.yaml tools.py agents/ skills/ README.md
.opencode/
skills/verify-output/SKILL.md
.hermit-deploy.json
dsh-workspace/
AGENTS.md
hermit/file-example/
ADAPTER.md exports.yaml tools.py agents/ skills/ README.md
.dsh/
hermit.patch.yml # the tools and the skills' folder; a session loads it with --patch
skills/verify-output/SKILL.md
.hermit-deploy.json
hermes-workspace/ # roles and hooks stay files under hermit/<id>/, named in .hermes.md
.hermes.md
hermit/file-example/
ADAPTER.md exports.yaml tools.py agents/ skills/ README.md
.hermes/
hermit.config.yaml # the tools and the skills' folder, to merge into ~/.hermes/config.yaml
skills/verify-output/SKILL.md
.hermit-deploy.json
Hermes Agent has no project file for MCP servers or skill folders: both are settings of its home’s config.yaml, which
a deployment never changes. .hermes/hermit.config.yaml is the part of it the deployment needs, for you to merge into
your own (mcp_servers.<adapter id>, skills.external_dirs with the absolute .hermes/skills,
context_file_max_chars). The hermes acting agent needs none of it: its Base Agent serves the adapter’s tools from
the session’s own tool server and gives the session the deployment’s skills folder.
Only declared exports are connected; every file is copied. A prompt-only adapter has no tool-server entry, skills,
roles or hooks to install, and its copy holds ADAPTER.md, exports.yaml and README.md. The generated deployment
report identifies the actual paths and role names, and lists every copied file with its digest.
Context is inserted into project instructions#
ADAPTER.md is the source. AGENTS.md, CLAUDE.md or .hermes.md is the host-facing result. The connector
inserts the rendered context between markers like these:
<!-- hermit:file-example:start -->
<!-- Rendered adapter instructions appear in this managed block. -->
<!-- hermit:file-example:end -->
The snippet shows the boundaries, not the complete generated contents. Redeployment replaces that adapter’s block and preserves project text outside it. Existing adapter headings are nested under the generated section title.
The deployment command prepares a workspace; it does not launch the agent. Its output must be empty or a workspace
previously generated for the same host. The source adapter and output workspace cannot contain one another.
A redeployment replaces the copy under hermit/<id>/: files the new version no longer has are removed. It also
replaces each exported skill’s copy in the host’s skills folder, and moves a skill the last deployment copied there
that the new version no longer exports to .retired-skills/ (a stale role goes to .retired-roles/), out of the
host’s discovery; a skill you put there yourself stays. It refuses,
before writing anything, when a copied file was changed or replaced (by a directory or a link) since the last
deployment or another file is in the way, when an exported skill would replace a skill folder no deployment wrote,
or when the skills folder is a link (or reached through one), and
names the file; an adapter link that leads outside the adapter is refused too.
The generated .codex/config.toml, .mcp.json, .pi/mcp.json, mini-swe-agent.yaml, opencode.json,
.dsh/hermit.patch.yml or .hermes/hermit.config.yaml is rewritten on deployment; it is not a general configuration
merger. Global host configuration is not modified.
Tools run from the adapter source#
Tool code is not copied into AGENTS.md. The generated MCP configuration starts a framework wrapper with the
adapter’s absolute path:
python -m hermit.runtime.mcp_server --adapter /absolute/path/to/adapter ...
That wrapper exposes the declared tool schemas, loads the Python functions, and returns their results to the
acting agent. The source adapter and its runtime dependencies must remain available. If DeepSeek Harness cannot start
the wrapper, it says so on its stderr and goes on without the tools: the dsh acting agent then fails the session,
but a session started by hand continues. Hermes Agent waits for its MCP servers before its first request and goes on
without one it could not reach: the hermes acting agent fails a session whose first request lacks the call’s tools.
Each tool declaration names an entrypoint such as tools.py:count_words and object input/output JSON Schemas.
The Python function may be synchronous or asynchronous. Subagents can also come from a Python exporter that returns
the list instead of a directory of files; the context is always the ADAPTER.md file.
An independent service is another integration option. The framework service can host adapter tools, shared state,
and reaction logic with its own lifecycle. The pipeline must start it and integrate any control channel with the
acting host. Ordinary deploy does not start that service.
Per-task context#
exports.yaml may name one of its declared tools as context_tool. That tool is the harness’s: it is called
once per task, before the agent’s first model call, with {query, task} (the task’s input text and its row), and
the text it returns is appended below ADAPTER.md for that task. The agent is never offered it: Session.tools,
tool_specs and respond leave it out. Session.context(query=..., task=...) makes the call; the built-in react
agent passes the task’s user message as the query and records the tool’s whole result in
RunOutput.extra["context_tool"], so the learning material says what the agent read. A workspace or a plugin is
installed once and has no per-task moment, so a template whose adapters declare a context tool sets
plugin-portable: false, and deploy and convert refuse them. The reharness template
retrieves reflections this way (ReHarness); the declaration is in the
manifest reference.
Custom acting pipelines#
A program that runs its own agent uses an adapter through Session, the Python counterpart of deploy and
convert:
from hermit import Session
session = Session("docs/_examples/file_adapter")
system_prompt = base_prompt + session.context(query=question, task=task) # ADAPTER.md, plus a context_tool's text
tools = task_tools + session.tool_specs("openai") # or "anthropic"; the adapter's tools beside the task's
...
for call in message["tool_calls"]: # a chat-completions turn
if session.has_tool(call["function"]["name"]):
messages.append(session.respond(call)) # the tool message; errors come back as text
session.context() without arguments is ADAPTER.md alone, as deploy renders it; with query and task, an
adapter whose manifest names a context_tool gets that tool’s text appended, and
session.last_context holds the tool’s whole result for RunOutput.extra["context_tool"].
session.call(name, arguments) runs one tool synchronously (also inside a running event loop), acall is the
coroutine, agents() and skills() give the other exports. Resources a tool may receive through its reserved
_resources parameter are bound at construction: deployment= (a host.json or its dict), learning_material=,
evidence= (a record directory), or any mapping under resources=. audit_log= writes one JSON line per call,
the same record hermit serve writes; the log must live outside the adapter directory, whose files the Trainer
keeps under version control, and Session refuses a path inside it. The task interface leaves host
integration to the pipeline; it does not automatically implement every export.
Outside a run’s task sandbox (a production program, say), Session(adapter, sandbox=True) keeps the adapter’s code
out of the program: the tools run in a hermit serve inside a sandbox (no network, the adapter read-only,
nothing writable but the evidence store), reached over MCP, and the audit log is still written by the program. Pass a
configured hermit.sandbox.Sandbox instead of True to grant more. deployment, learning_material and
evidence go with it; other resources are refused, and so is an adapter whose subagents come from a Python exporter.
Close the session, or use it in a with block, to stop the server.
Evolution interface#
What does the Evolver edit?#
At the start of each step, the Trainer exports the accepted Git version into ordinary working files. The acting batch and the learner receive separate copies:
Location in a run |
Purpose |
Who changes it? |
|---|---|---|
|
Template reference for the specification. |
Prepared by the Trainer. |
|
Adapter supplied to the current acting batch. |
Prepared by the Trainer; the pipeline treats it as input. |
|
Candidate files being learned. |
Evolver edits these files. |
|
Git worktree holding the recorded adapter version. |
Trainer updates and commits it. |
|
Method-specific search or learning state. |
Evolver; separate from the adapter. |
The learner’s path is ctx.workspace.adapter. A scripted Evolver can use normal file operations; a learner agent
can edit the same files through its file tools. For example, this method appends a predefined instruction:
from hermit.agent.evolver.base import StepContext, StepResult
def step(self, ctx: StepContext) -> StepResult:
path = ctx.workspace.adapter / "ADAPTER.md"
path.write_text(path.read_text() + "\nCheck the result against the task requirements.\n")
return StepResult(status="done", summary="Added a result-checking instruction")
This demonstrates the file handoff, not a learning strategy. A real method chooses its edits from the available
evidence. It leaves the selected candidate in the directory and returns status and usage through StepResult.
The Evolver edits ADAPTER.md or other permitted source files. It does not edit the acting workspace’s generated
AGENTS.md as its learned artifact. After acceptance, a later pipeline execution loads or redeploys the new source
version. An already-running host does not automatically receive a live update.
How does the specification limit edits?#
The template declares the writable content and fixed content. Here is the example’s actual specification:
structure:
learnable:
- exports.yaml
- path: ADAPTER.md
format: {text: true, max_bytes: 4000}
- path: agents/*.md
format: {text: true, max_bytes: 4000, frontmatter: [name, description]}
- path: skills/**
format: {text: true, max_bytes: 4000, max_files: 8}
fixed:
- tools.py
- README.md
For this template:
Proposed edit |
Result |
|---|---|
Rewrite |
Allowed, within its format and size limit. |
Edit |
Allowed if its frontmatter keeps |
Add or edit a skill under |
Allowed, within the declared file and size limits. |
Edit |
Rejected: it is fixed here. |
Delete |
Allowed: the adapter then exports no context. |
Add an undeclared file elsewhere in the adapter. |
Rejected: it is outside the learnable paths. |
Change the tool declarations in |
Allowed, if the file parses (check 3) and the tools still load (check 5). |
Edit |
Rejected: |
Another template can permit tool-code changes or other learnable files. The scope comes from that template; it is not a hard-coded restriction to prompts.
The candidate directory is writable, but not every edit is acceptable. Fixed-file protection is enforced by the
specification check after the learner returns, rather than by making each fixed file physically read-only inside
the working copy. The template’s .hermit/EVOLVER.md explains the intended editing rules to the learner.
Who checks and records the candidate?#
The Trainer compares changed files with the template specification. It checks .hermit/ and fixed paths, allowed
paths, that exports.yaml parses, formats, and export loading. If a candidate violates the specification, it records the invalid version,
restores affected files from the template or previous adapter, checks again, and records the repair.
The next batch uses the accepted version. The learner sees any repair feedback in its next learning material.
By default a learner may change everything in the adapter except .git/ and .hermit/. Every other limit is added
by the template (structure and its check) or by the Evolver itself. In MWM, for example, the Evolver protects
interface.py and mwm_core/, and the template’s check keeps the wm tool in exports.yaml. .hermit/ is carried byte-for-byte as the tree’s root has it, except
.hermit/CARD.md, which only the Trainer and hermit eval write. structure and check are always read from the
template root. See failure handling.
Specification check#
The callable interface is check_spec(adapter, root) -> CheckResult. The result contains passed and issues
naming the affected path, check, and problem. It establishes conformance and loadability; it does not measure task
performance.
The built-in load check renders context, loads role declarations, and imports declared tools. It does not launch the acting host or service. Additional runtime requirements belong in the template’s custom check or task setup.
A template may add a checker for requirements not expressed by structure:
from pathlib import Path
def check(adapter_path: str) -> list[dict]:
if not (Path(adapter_path) / "ADAPTER.md").read_text().strip():
return [{"path": "ADAPTER.md", "problem": "instructions must not be empty"}]
return []
Save it as .hermit/check.py and declare it as check: .hermit/check.py:check. The checker is loaded from the
template root. Return a nonempty issue list
to reject a candidate; a dictionary with an issues list is also accepted. It runs in a subprocess with a
120-second limit and network isolation when bubblewrap is available.
Minimal example#
From the repository root after installation, use fresh output directories:
mkdir -p .demo
cp -R docs/_examples/file_adapter .demo/file-adapter
hermit deploy --adapter .demo/file-adapter --workspace .demo/file-codex --host codex
hermit deploy --adapter .demo/file-adapter --workspace .demo/file-claude --host claude-code
Inspect .demo/file-codex/AGENTS.md, .demo/file-claude/CLAUDE.md, and the generated roles, skills, and tool
configuration. No model is called by these deployment commands.
After editing the source copy, check it against the template:
python -m hermit.spec .demo/file-adapter --root docs/_examples/file_adapter
Then rerun the deployment command to refresh host files. This is the same source-edit → check → deploy boundary used during training, with the Trainer additionally managing candidate acceptance and Git versions.
Directory, Git version, and runtime state#
The portable artifact is the adapter directory. The Trainer keeps a Git tree of its versions, with run branches,
checkpoint tags, and a final tag. The learner’s exported working copy is not itself a Git worktree and does not
need a .git/ directory. The Trainer performs the version-control operations.
Deployment consumes the adapter files. Learner state, execution logs, and a service’s per-run state stay outside
the package unless a template explicitly makes some evidence or memory part of its learned content.
.hermit/CARD.md records provenance and evaluations; it is not acting context.