Hermit
Spend premium agent tokens on judgment, not on routine execution.
Hermit is a small MCP coding executor for Claude Code and Codex. Your paid host agent plans, reviews, and makes the important calls; Hermit delegates bounded repository work—reading and editing files, running commands, and tests—to a local or lower-cost executor model.
It is a cost-optimization layer for agentic coding, not another chat UI and not a replacement for Claude Code or Codex.
Claude Code or Codex: plan, review, decide
│ delegate a bounded task
▼
Hermit: execute with a local or lower-cost model
│ return status and result
▼
Claude Code or Codex: verify and continue
Install and run your first task
Requires Node.js 20+ and Python 3.11+.
Hermit deliberately does not use the Claude or Codex subscription as its
executor. Before delegating work, configure either a local Ollama model or one
OpenAI-compatible endpoint. hermit doctor verifies this explicitly, so a
host registration alone is never presented as a working executor.
1. Install Hermit
npm install -g @cafitac/hermit-agent
2. Choose an executor
For a local, no-per-token-cost executor:
ollama pull qwen3-coder:30b
For any OpenAI-compatible Chat Completions API, keep the secret in your shell or operating-system secret store and register only its environment-variable name:
export BUDGET_PROVIDER_API_KEY="…"
hermit configure \
--model coder-small \
--base-url https://llm.example.com/v1 \
--api-key-env BUDGET_PROVIDER_API_KEY
hermit configure never accepts or writes an API key. It stores the endpoint,
model, and environment-variable reference in ~/.hermit/settings.json.
3. Register the host
Claude Code
hermit install claude
Codex
hermit install codex
hermit install claude registers only Claude Code, and hermit install codex
registers only Codex. Bare hermit install registers both hosts. Each command
creates local Hermit settings if needed, starts or recovers the local gateway,
and registers this stable stdio command with the selected host:
hermit mcp-server
The gateway binds to loopback only. If another process owns its default port, Hermit leaves that process untouched and selects a free local port for its own gateway.
4. Verify readiness
hermit doctor
Only delegate work after it reports a ready executor. Restart the selected host
after installation. hermit install codex writes the shared Codex MCP
configuration, so the same registration is available to the Codex CLI, desktop
app, and IDE extension after they restart.
Claude Desktop
Download hermit-<version>.mcpb from the matching GitHub Release and either
double-click it or choose Settings → Extensions → Advanced settings → Install
Extension in Claude Desktop. The extension uses the MCPB UV runtime, so it
installs Hermit's matching PyPI dependency without requiring a global Python
installation. It creates ~/.hermit/settings.json on first launch. It supports
Claude Desktop on macOS and Windows; network access is required the first time
UV resolves the Hermit package. The installation screen optionally accepts an
executor model, OpenAI-compatible base URL, and API key; these values are held
by Claude Desktop and applied only to Hermit's MCP process, rather than written
to settings.json. Leave them blank to keep existing Hermit/Ollama settings.
Use
Ask Claude Code or Codex to delegate a scoped repository task to Hermit. The MCP server exposes four task-lifecycle tools:
run_task(task, cwd, model?, max_turns?)check_task(task_id)reply_task(task_id, message)cancel_task(task_id)
run_task starts a background task. Poll with check_task; if Hermit needs
input or a permission decision, reply through reply_task.
Hermit also supplies a small server instruction that recommends delegation for bounded implementation, debugging, test, and maintenance work. It is guidance, not a hidden autopilot: the host still owns the decision to delegate.
Quality and multi-agent work
run_task defaults to strategy: "single": one low-cost executor, with no
quality trade-off from orchestration. For a complex refactor, migration, or
security-sensitive change, the host can use strategy: "auto". Hermit then
runs a read-only planner, one writing executor, and a read-only reviewer.
There are never parallel writing agents. If the reviewer does not return
VERDICT: PASS, Hermit returns needs_review instead of done; the host gets
the execution result and review findings together. Users can make auto their
local default in ~/.hermit/settings.json:
{
"orchestration": {
"mode": "auto",
"max_agents": 3,
"allow_parallel_writes": false
}
}
Configuration
Settings live at ~/.hermit/settings.json. hermit configure is the preferred
way to configure a remote executor because it persists an environment-variable
reference rather than an API key. The default routing tries a configured GLM
provider first, then a locally installed Ollama model:
{
"routing": {
"priority_models": [
{"model": "glm-5.1"},
{"model": "qwen3-coder:30b"}
]
}
}
Use Ollama for a local executor (no per-token API cost) or any provider that offers the OpenAI-compatible Chat Completions API with tool calling. Give a custom endpoint an explicit provider profile; model names never need to match a built-in prefix:
{
"providers": {
"budget-provider": {
"base_url": "https://llm.example.com/v1",
"api_key_env": "BUDGET_PROVIDER_API_KEY"
}
},
"routing": {
"priority_models": [
{"model": "coder-small", "provider": "budget-provider"},
{"model": "qwen3-coder:30b"}
]
}
}
Codex is a supported MCP host; it is not part of the default executor fallback chain.
Architecture
Claude Code or Codex
│ MCP over stdio
▼
hermit mcp-server
│ REST + task status
▼
FastAPI gateway (loopback)
▼
AgentLoop → repository tools → local/flat-rate LLM
The gateway owns background execution, cancellation, permission waits, model routing, and task state. The MCP process stays small and transports only the four public task operations.
Development
.venv/bin/python -m pytest tests/
Hermit is MIT licensed and currently in alpha.
1 maintainer
Release files for cafitac-hermit-agent 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cafitac_hermit_agent-0.4.1.tar.gz | 147.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cafitac_hermit_agent-0.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 352.6 kB
Release files / cafitac_hermit_agent-0.4.1.tar.gz
| Download URL | cafitac_hermit_agent-0.4.1.tar.gz |
|---|---|
| Size | 147.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3819f9f298b7b510edbcb503e38e8bb9930c01b9138a3a16338e6b22d4f3292
|
|
BLAKE2b-256 checksum How to use checksums |
b37e42a64e3fd146816e32e6826f922cfc28f421ce3cfe7b8a7d96c1073431d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / cafitac_hermit_agent-0.4.1-py3-none-any.whl
| Download URL | cafitac_hermit_agent-0.4.1-py3-none-any.whl |
|---|---|
| Size | 204.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cac174dfcca1419c8c49c13f29fea9485aed9a01578399a9d73e130a225e0332
|
|
BLAKE2b-256 checksum How to use checksums |
4e1b0a1155ae3b5396140bd703b383379ed7c8e2cdbb2c22e9887c8c01bbed1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
