Skip to content

The open-source app everyone uses to manage agents at work

fix(adapters): restore built-in Hermes and sync lockfile with server

HenkDzf884cbab78f9
diff --git a/docs/adapters/overview.md b/docs/adapters/overview.md
index 55fd4d4e9d..dfb4b21fb3 100644
--- a/docs/adapters/overview.md
+++ b/docs/adapters/overview.md
@@ -24,6 +24,7 @@ When a heartbeat fires, Paperclip:
| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
| Cursor | `cursor` | Runs Cursor in background mode |
| Pi Local | `pi_local` | Runs an embedded Pi agent locally |
+| Hermes Local | `hermes_local` | Runs Hermes CLI locally (`hermes-paperclip-adapter`) |
| OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint |
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
@@ -35,7 +36,6 @@ These adapters ship as standalone npm packages and are installed via the plugin
| Adapter | Package | Type Key | Description |
|---------|---------|----------|-------------|
| Droid Local | `@henkey/droid-paperclip-adapter` | `droid_local` | Runs Factory Droid locally |
-| Hermes Local | `@henkey/hermes-paperclip-adapter` | `hermes_local` | Runs Hermes CLI locally |
## External Adapters
@@ -78,7 +78,7 @@ my-adapter/
## Choosing an Adapter
-- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, or install `droid_local` / `hermes_local` as external plugins
+- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, or install `droid_local` as an external plugin
- **Need to run a script or command?** Use `process`
- **Need to call an external service?** Use `http`
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter) or [build an external adapter plugin](/adapters/external-adapters)
diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md
index dffb6fe29a..cafc39e975 100644
--- a/docs/agents-runtime.md
+++ b/docs/agents-runtime.md
@@ -39,6 +39,7 @@ Built-in adapters:
- `opencode_local`: runs your local `opencode` CLI
- `cursor`: runs Cursor in background mode
- `pi_local`: runs an embedded Pi agent locally
+- `hermes_local`: runs your local `hermes` CLI (`hermes-paperclip-adapter`)
- `openclaw_gateway`: connects to an OpenClaw gateway endpoint
- `process`: generic shell command adapter
- `http`: calls an external HTTP endpoint
@@ -46,9 +47,8 @@ Built-in adapters:
External plugin adapters (install via the adapter manager or API):
- `droid_local`: runs your local Factory Droid CLI (`@henkey/droid-paperclip-adapter`)
-- `hermes_local`: runs your local `hermes` CLI (`@henkey/hermes-paperclip-adapter`)
-For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `droid_local`, `hermes_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.
+For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `droid_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.
## 3.2 Runtime behavior
@@ -177,7 +177,7 @@ Start with least privilege where possible, and avoid exposing secrets in broad r
## 10. Minimal setup checklist
-1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` and `hermes_local` are also available via the adapter manager.
+1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` are also available via the adapter manager.
2. Set `cwd` to the target workspace (for local adapters).
3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle.
4. Configure heartbeat policy (timer and/or assignment wakeups).
diff --git a/server/package.json b/server/package.json
index b519ed1a7f..4b95606abb 100644
--- a/server/package.json
+++ b/server/package.json
@@ -66,6 +66,7 @@
"drizzle-orm": "^0.38.4",
"embedded-postgres": "^18.1.0-beta.16",
"express": "^5.1.0",
+ "hermes-paperclip-adapter": "^0.2.0",
"jsdom": "^28.1.0",
"multer": "^2.0.2",
"open": "^11.0.0",
diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.ts
new file mode 100644
index 0000000000..463a56945f
--- /dev/null
+++ b/server/src/adapters/builtin-adapter-types.ts
@@ -0,0 +1,15 @@
+/**
+ * Adapter types shipped with Paperclip. External plugins must not replace these.
+ */
+export const BUILTIN_ADAPTER_TYPES = new Set([
+ "claude_local",
+ "codex_local",
+ "cursor",
+ "gemini_local",
+ "openclaw_gateway",
+ "opencode_local",
+ "pi_local",
+ "hermes_local",
+ "process",
+ "http",
+]);
diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.ts
index 35ae45c57d..aa8ddeb465 100644
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -67,6 +67,21 @@ import {
import {
agentConfigurationDoc as piAgentConfigurationDoc,
} from "@paperclipai/adapter-pi-local";
+import {
+ execute as hermesExecute,
+ testEnvironment as hermesTestEnvironment,
+ sessionCodec as hermesSessionCodec,
+ listSkills as hermesListSkills,
+ syncSkills as hermesSyncSkills,
+ detectModel as detectModelFromHermes,
+} from "hermes-paperclip-adapter/server";
+import {
+ agentConfigurationDoc as hermesAgentConfigurationDoc,
+ models as hermesModels,
+} from "hermes-paperclip-adapter";
+import { BUILTIN_ADAPTER_TYPES } from "./builtin-adapter-types.js";
+import { buildExternalAdapters } from "./plugin-loader.js";
+import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";
import { processAdapter } from "./process/index.js";
import { httpAdapter } from "./http/index.js";
@@ -163,6 +178,19 @@ const piLocalAdapter: ServerAdapterModule = {
agentConfigurationDoc: piAgentConfigurationDoc,
};
+const hermesLocalAdapter: ServerAdapterModule = {
+ type: "hermes_local",
+ execute: hermesExecute,
+ testEnvironment: hermesTestEnvironment,
+ sessionCodec: hermesSessionCodec,
+ listSkills: hermesListSkills,
+ syncSkills: hermesSyncSkills,
+ models: hermesModels,
+ supportsLocalAgentJwt: true,
+ agentConfigurationDoc: hermesAgentConfigurationDoc,
+ detectModel: () => detectModelFromHermes(),
+};
+
const adaptersByType = new Map<string, ServerAdapterModule>();
function registerBuiltInAdapters() {
@@ -174,6 +202,7 @@ function registerBuiltInAdapters() {
cursorLocalAdapter,
geminiLocalAdapter,
openclawGatewayAdapter,
+ hermesLocalAdapter,
processAdapter,
httpAdapter,
]) {
@@ -184,15 +213,12 @@ function registerBuiltInAdapters() {
registerBuiltInAdapters();
// ---------------------------------------------------------------------------
-// Load external adapter plugins (droid, hermes, etc.)
+// Load external adapter plugins (e.g. droid_local)
//
// External adapter packages export createServerAdapter() which returns a
// ServerAdapterModule. The host fills in sessionManagement.
// ---------------------------------------------------------------------------
-import { buildExternalAdapters } from "./plugin-loader.js";
-import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";
-
/** Cached sync wrapper — the store is a simple JSON file read, safe to call frequently. */
function getDisabledAdapterTypesFromStore(): string[] {
return getDisabledAdapterTypes();
@@ -208,6 +234,12 @@ const externalAdaptersReady: Promise<void> = (async () => {
try {
const externalAdapters = await buildExternalAdapters();
for (const externalAdapter of externalAdapters) {
+ if (BUILTIN_ADAPTER_TYPES.has(externalAdapter.type)) {
+ console.warn(
+ `[paperclip] Skipping external adapter "${externalAdapter.type}" — conflicts with built-in adapter`,
+ );
+ continue;
+ }
adaptersByType.set(
externalAdapter.type,
{
diff --git a/server/src/routes/adapters.ts b/server/src/routes/adapters.ts
index c50d558122..579ed31d49 100644
--- a/server/src/routes/adapters.ts
+++ b/server/src/routes/adapters.ts
@@ -39,25 +39,10 @@ import type { ServerAdapterModule } from "../adapters/types.js";
import { loadExternalAdapterPackage, getUiParserSource, getOrExtractUiParserSource, reloadExternalAdapter } from "../adapters/plugin-loader.js";
import { logger } from "../middleware/logger.js";
import { assertBoard } from "./authz.js";
+import { BUILTIN_ADAPTER_TYPES } from "../adapters/builtin-adapter-types.js";
const execFileAsync = promisify(execFile);
-// ---------------------------------------------------------------------------
-// Known built-in adapter types (cannot be removed via the API)
-// ---------------------------------------------------------------------------
-
-const BUILTIN_ADAPTER_TYPES = new Set([
- "claude_local",
- "codex_local",
- "cursor",
- "gemini_local",
- "openclaw_gateway",
- "opencode_local",
- "pi_local",
- "process",
- "http",
-]);
-
// ---------------------------------------------------------------------------
// Request / Response types
// ---------------------------------------------------------------------------
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 36a87d6338..8bf2a1045f 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -76,6 +76,7 @@ export function agentRoutes(db: Db) {
codex_local: "instructionsFilePath",
droid_local: "instructionsFilePath",
gemini_local: "instructionsFilePath",
+ hermes_local: "instructionsFilePath",
opencode_local: "instructionsFilePath",
cursor: "instructionsFilePath",
pi_local: "instructionsFilePath",
diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.ts
index cbaae0119d..fe80927396 100644
--- a/ui/src/adapters/adapter-display-registry.ts
+++ b/ui/src/adapters/adapter-display-registry.ts
@@ -16,6 +16,7 @@ import {
Cpu,
} from "lucide-react";
import { OpenCodeLogoIcon } from "@/components/OpenCodeLogoIcon";
+import { HermesIcon } from "@/components/HermesIcon";
// ---------------------------------------------------------------------------
// Type suffix parsing
@@ -73,6 +74,11 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {
description: "Local multi-provider agent",
icon: OpenCodeLogoIcon,
},
+ hermes_local: {
+ label: "Hermes Agent",
+ description: "Local Hermes CLI agent",
+ icon: HermesIcon,
+ },
pi_local: {
label: "Pi",
description: "Local Pi agent",
diff --git a/ui/src/adapters/hermes-local/config-fields.tsx b/ui/src/adapters/hermes-local/config-fields.tsx
new file mode 100644
index 0000000000..4b80704365
--- /dev/null
+++ b/ui/src/adapters/hermes-local/config-fields.tsx
@@ -0,0 +1,49 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+ Field,
+ DraftInput,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+ "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+ "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
+
+export function HermesLocalConfigFields({
+ isCreate,
+ values,
+ set,
+ config,
+ eff,
+ mark,
+ hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+ if (hideInstructionsFile) return null;
+ return (
+ <Field label="Agent instructions file" hint={instructionsFileHint}>
+ <div className="flex items-center gap-2">
+ <DraftInput
+ value={
+ isCreate
+ ? values!.instructionsFilePath ?? ""
+ : eff(
+ "adapterConfig",
+ "instructionsFilePath",
+ String(config.instructionsFilePath ?? ""),
+ )
+ }
+ onCommit={(v) =>
+ isCreate
+ ? set!({ instructionsFilePath: v })
+ : mark("adapterConfig", "instructionsFilePath", v || undefined)
+ }
+ immediate
+ className={inputClass}
+ placeholder="/absolute/path/to/AGENTS.md"
+ />
+ <ChoosePathButton />
+ </div>
+ </Field>
+ );
+}
diff --git a/ui/src/adapters/hermes-local/index.ts b/ui/src/adapters/hermes-local/index.ts
new file mode 100644
index 0000000000..93d9ed6aca
--- /dev/null
+++ b/ui/src/adapters/hermes-local/index.ts
@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseHermesStdoutLine } from "hermes-paperclip-adapter/ui";
+import { HermesLocalConfigFields } from "./config-fields";
+import { buildHermesConfig } from "hermes-paperclip-adapter/ui";
+
+export const hermesLocalUIAdapter: UIAdapterModule = {
+ type: "hermes_local",
+ label: "Hermes Agent",
+ parseStdoutLine: parseHermesStdoutLine,
+ ConfigFields: HermesLocalConfigFields,
+ buildAdapterConfig: buildHermesConfig,
+};
diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.ts
index a27e7316fb..8c48ecbc3c 100644
--- a/ui/src/adapters/registry.ts
+++ b/ui/src/adapters/registry.ts
@@ -6,6 +6,7 @@ import { geminiLocalUIAdapter } from "./gemini-local";
import { openCodeLocalUIAdapter } from "./opencode-local";
import { piLocalUIAdapter } from "./pi-local";
import { openClawGatewayUIAdapter } from "./openclaw-gateway";
+import { hermesLocalUIAdapter } from "./hermes-local";
import { processUIAdapter } from "./process";
import { httpUIAdapter } from "./http";
import { loadDynamicParser } from "./dynamic-loader";
@@ -18,6 +19,7 @@ function registerBuiltInUIAdapters() {
claudeLocalUIAdapter,
codexLocalUIAdapter,
geminiLocalUIAdapter,
+ hermesLocalUIAdapter,
openCodeLocalUIAdapter,
piLocalUIAdapter,
cursorLocalUIAdapter,