Hermit

Spend premium agent tokens on judgment, not on routine execution.

Hermit is a cost-optimized MCP coding executor for Claude Code, Codex, and Claude Desktop. 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.

5. Delegate one bounded task

In Claude Code, Codex, or Claude Desktop, ask the host agent:

Use Hermit's run_task tool to add a focused test for <change> in this repository.

Hermit returns a task ID immediately. The host polls it with check_task, and uses reply_task only if Hermit asks a question or permission decision. If the executor is not ready, run_task does not create a task; it returns the same specific diagnosis and setup command shown by hermit doctor.

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, Codex, or Claude Desktop 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.