Hermit
Deploy an existing adapter#
Use a context-only adapter first: it needs no dataset, service, or model calls to generate a host workspace. Deployment writes files the acting host will read; it does not start the host.
1. Prepare an adapter#
From the repository root:
mkdir -p .demo
cp -R hermit/algorithms/templates/prompt_only .demo/deploy-adapter
python -c 'from pathlib import Path; Path(".demo/deploy-adapter/ADAPTER.md").write_text("# Working rules\n\nCheck units before doing arithmetic.\n")'
python -m hermit.spec .demo/deploy-adapter --root hermit/algorithms/templates/prompt_only
Use a fresh destination for the copy. You can instead use a trained <run>/checkout/ with its compatible template.
2. Generate and inspect a workspace#
hermit deploy --adapter .demo/deploy-adapter --workspace .demo/deploy-codex --host codex
cat .demo/deploy-codex/AGENTS.md
cat .demo/deploy-codex/.codex/config.toml
AGENTS.md should contain the units rule in a managed adapter block. This adapter has no tools or roles, so the
report’s server is null and the configuration contains no adapter MCP entry.
The workspace must be empty or already generated by the framework for the same host, and separate from the adapter directory. An arbitrary nonempty project is refused. Within an existing generated workspace, redeployment replaces generated host configuration and the managed context block; do not store hand-written settings in generated files you expect to keep unchanged.
3. Update and redeploy#
python -c 'from pathlib import Path; Path(".demo/deploy-adapter/ADAPTER.md").write_text("# Working rules\n\nCheck units and dates before doing arithmetic.\n")'
hermit deploy --adapter .demo/deploy-adapter --workspace .demo/deploy-codex --host codex
cat .demo/deploy-codex/AGENTS.md
The managed block should now contain units and dates, with no duplicate adapter block. If Codex is installed and authenticated, start it separately:
cd .demo/deploy-codex
codex
Return to the repository root for the remaining commands. For Claude Code use a separate destination and
--host claude-code; inspect its CLAUDE.md. Host installation and actual model calls are outside file generation.
4. Convert to a native plugin#
From the repository root, this context-only adapter can be converted for Claude Code:
hermit convert --adapter .demo/deploy-adapter --output .demo/deploy-plugin --target claude-code
python -c 'from pathlib import Path; print("\n".join(str(p) for p in sorted(Path(".demo/deploy-plugin").rglob("*")) if p.is_file()))'
Inspect the conversion JSON and the emitted marketplace/plugin files. Conversion embeds the adapter and produces a package to install using the target’s plugin commands; it does not install or enable the plugin. Native plugin targets have different export capabilities. For example, a nonempty context is refused for Codex and Pi conversion; workspace deployment is a different route.
Do not use --allow-lossy just to make a refusal disappear: check whether omitting the reported export would
remove the behavior you intend to ship. See the capability matrix.
Tools, roles, and services#
docs/_examples/file_adapter/ demonstrates roles, skills, and a simple count_words tool.
Tool adapters require the framework and their dependencies in the Python environment where the generated tool
server runs. Workspace tool configuration uses absolute source paths; keep that adapter directory available.
The Lean collaboration adapter additionally needs a running team service, Lean/Mathlib, and per-agent settings. Follow its complete recipe before starting hosts; generating workspace files alone does not make the team service available.
To assess whether a deployed adapter helps a different acting host, run an appropriate evaluation. File generation is not a performance measurement.