hermes-paperclip-adapter

To enable the adapter, you must register it in your Paperclip server's adapter registry (typically located at server/src/adapters/registry.ts). You need to import the adapter and its specific server-side functions: execute, testEnvironment, detectModel, listSkills, syncSkills, and sessionCodec.

import * as hermesLocal from "hermes-paperclip-adapter";
import {
  execute,
  testEnvironment,
  detectModel,
  listSkills,
  syncSkills,
  sessionCodec,
} from "hermes-paperclip-adapter/server";

registry.set("hermes_local", {
  ...hermesLocal,
  execute,
  testEnvironment,
  detectModel,
  listSkills,
  syncSkills,
  sessionCodec,
});

Install the adapter via npm to allow Paperclip to manage Hermes Agent as an employee.

Prerequisites

• Hermes Agent installed via pip install hermes-agent.
• Python 3.10+.
• At least one LLM API key (Anthropic, OpenRouter, or OpenAI).

npm install hermes-paperclip-adapter

If you provide a custom promptTemplate in the Hermes configuration, you can use the following variables to inject context from the Paperclip environment:

• {{agentId}}: Paperclip agent ID
• {{agentName}}: Agent display name
• {{companyId}}: Paperclip company ID
• {{companyName}}: Company display name
• {{runId}}: Current heartbeat run ID
• {{taskId}}: Current task/issue ID (if assigned)
• {{taskTitle}}: Task title (if assigned)
• {{taskBody}}: Task description (if assigned)
• {{projectName}}: Project name (if scoped to a project)

You can provide a custom promptTemplate using {{variable}} syntax to control how tasks are presented to the agent.

Available Variables

• {{agentId}}: Paperclip agent ID
• {{agentName}}: Agent display name
• {{companyId}}: Company ID
• {{companyName}}: Company name
• {{runId}}: Current heartbeat run ID
• {{taskId}}: Assigned task/issue ID
• {{taskTitle}}: Task title
• {{taskBody}}: Task instructions
• {{projectName}}: Project name
• {{paperclipApiUrl}}: Paperclip API base URL
• {{commentId}}: Comment ID (when woken by a comment)
• {{wakeReason}}: Reason this run was triggered

Conditional Sections

• {{#taskId}}...{{/taskId}}: Included only when a task is assigned.
• {{#noTask}}...{{/noTask}}: Included only when no task is present (heartbeat check).
• {{#commentId}}...{{/commentId}}: Included only when woken by a comment.

If no explicit provider is configured, the adapter attempts to infer the correct provider by matching the model name against known prefixes. The following mapping is used:

When determining which provider to use for a model, the adapter follows a specific priority chain to ensure correct routing. The resolution order is:

1. Explicit Provider: If an explicitProvider is provided via the adapterConfig (user override), it takes highest priority.
2. Hermes Config: If a provider is defined in ~/.hermes/config.yaml, it is used only if the detectedModel in the config matches the requested model name (case-insensitive).
3. Model Inference: If no explicit or config-based provider is found, the adapter attempts to infer the provider from the model name prefix (e.g., gpt- might map to copilot).
4. Auto: If all else fails, the provider defaults to auto, allowing Hermes to handle detection.

Once registered, create an agent in the Paperclip UI or via API using the hermes_local adapter type. You can configure the model, iteration limits, timeouts, and enabled toolsets in the adapterConfig object.

{
  "name": "Hermes Engineer",
  "adapterType": "hermes_local",
  "adapterConfig": {
    "model": "anthropic/claude-sonnet-4",
    "maxIterations": 50,
    "timeoutSec": 300,
    "persistSession": true,
    "enabledToolsets": ["terminal", "file", "web"]
  }
}

The Hermes adapter reads model configuration from ~/.hermes/config.yaml. To define your default model and its associated settings, use the model: section in the YAML file.

Supported keys under the model: section:

• default: The model name (e.g., gpt-5.4 or anthropic/claude-sonnet-4).
• provider: The provider name (e.g., copilot, zai, anthropic).
• base_url: An optional base URL override for the API.
• api_mode: The API mode to use (e.g., chat_completions, codex_responses).

The adapter provides utilities to identify which LLM model is being used and which provider (e.g., OpenAI, Anthropic) is responsible for it. This is useful for configuring agent capabilities based on the underlying model.

Available functions:

• detectModel: Identifies a model from input.
• parseModelFromConfig: Extracts model information from a configuration object.
• resolveProvider: Determines the provider for a given model.
• inferProviderFromModel: Infers the provider based on the model name.

import {
  detectModel,
  parseModelFromConfig,
  resolveProvider,
  inferProviderFromModel
} from "./detect-model.js";