feat: add Hermes Agent as core adapter

[HenkDz]

Summary

Adds Hermes Agent (https://github.com/NousResearch/hermes-agent) as a first-party core adapter, joining Claude, Codex, OpenCode, Cursor, Gemini, and Pi.

Hermes Agent is a full-featured open-source AI agent by Nous Research with 30+ native tools (terminal, file, web, browser, vision, etc.), persistent memory, skills, session persistence, MCP support, and multi-provider model routing.

Changes

Core adapter (packages/adapters/hermes-local/)

• Complete in-tree adapter implementation following the same conventions as other core adapters
• execute() — spawns hermes chat with adapter config, tags sessions with --source tool to isolate from user history
• detectModel() — auto-detects the user's configured model/provider from ~/.hermes/.env
• listSkills() / syncSkills() — maps between Hermes skills and Paperclip skills
• parseStdoutLine() — parses Hermes output into Paperclip transcript entries (tool_call/tool_result pairs)
• testEnvironment() — verifies hermes CLI is available and functional

Server (server/)

• Registered hermes_local in adapter registry with detectModel support
• detectAdapterModel() API endpoint for auto-detecting adapter model/provider
• ENABLED_ADAPTER_TYPES and ENABLED_INVITE_ADAPTERS include hermes_local

UI (ui/)

• Custom HermesIcon SVG component (caduceus — winged staff with serpents) replacing the generic Zap icon
• Adapter config form with Hermes-specific placeholder (hermes instead of claude)
• Model dropdown supports free-text input (Hermes works with any provider/model)
• Auto-detects model from Hermes config and pre-fills model dropdown
• Onboarding wizard and New Agent dialog include Hermes as a first-class option

Session isolation

• Agent sessions are tagged source=tool via --source tool flag (requires hermes-agent >= 2026.03)
• This prevents agent sessions from polluting the user's hermes sessions list/browse/search history
• Works with upstream PR NousResearch/hermes-agent#3255 (merged)

Adapter configuration doc

The adapter includes a comprehensive agentConfigurationDoc that guides users through:

• Prerequisites (Python 3.10+, hermes CLI, API keys)
• Core config (model, provider, timeout)
• Tool configuration (toolsets)
• Session & workspace options
• Template variables ({{agentName}}, {{taskTitle}}, etc.)

Testing

• All typechecks pass: @paperclipai/adapter-hermes-local, @paperclipai/server, @paperclipai/ui
• Rebased cleanly on upstream master

[greptile-apps]

Greptile Summary

This PR promotes the Hermes Agent adapter from an external npm package (hermes-paperclip-adapter@0.1.1) to a first-party in-tree adapter (@paperclipai/adapter-hermes-local), following the same conventions as Claude, Codex, OpenCode, Cursor, Gemini, and Pi. The migration is clean — the old dependency is removed from server/package.json and all imports are updated. New capabilities over the external package include listSkills/syncSkills, a detectModel API endpoint with a UI affordance (auto-fill from ~/.hermes/config.yaml), a creatable free-text model dropdown, and a custom caduceus HermesIcon.\n\nKey findings:\n\n- post-process.ts ships as dead code (P1): The 296-line postProcessMessage function is never exported from src/ui/index.ts and has no references anywhere in the repo. It should be wired up or removed.\n- Unused KAOMOJI_RE constant (P2): Defined in parse-stdout.ts but stripKaomoji uses its own inline regex instead.\n- Dead conditional in normalizeHermesTableBlock (P2): Both branches of the if/else call lines.pop(), making the condition a no-op.\n- Comment/PR-number mismatch (P2): execute.ts attributes --source tool to PR #3208 while the PR description cites #3255.\n- Duplicate JSDoc block on models export (P2): Two consecutive JSDoc comments in src/index.ts.\n- PR description missing "thinking path" and screenshots: The PR body does not include the required top-down thinking path, nor before/after screenshots for the UI changes (new icon, model dropdown, adapter dialog entries). Please add these per CONTRIBUTING.md.

Confidence Score: 3/5

Safe to merge after resolving the dead post-process.ts module and adding the missing PR description sections required by CONTRIBUTING.md.

The core adapter logic (execute, testEnvironment, sessionCodec, skills, detectModel) is well-structured and follows existing adapter conventions. The server migration from the external package is complete and correct. The primary concern is post-process.ts — 296 lines of complex table/banner normalization code that is never called; shipping dead code of this size in a new package is a meaningful quality issue. Combined with the CONTRIBUTING.md requirement for a thinking path and screenshots (absent for a PR touching UI dialogs, a new icon, and the model dropdown), the PR is not quite on the merge path without those fixes.

packages/adapters/hermes-local/src/ui/post-process.ts — either wire up postProcessMessage or remove the file. Also review the KAOMOJI_RE dead constant in parse-stdout.ts.

Important Files Changed

Filename	Overview
packages/adapters/hermes-local/src/ui/post-process.ts	296-line post-processor for Hermes-specific markdown — postProcessMessage is never exported from src/ui/index.ts and has no references anywhere in the repo. Ships as dead code. Also contains a redundant if/else where both branches call lines.pop().
packages/adapters/hermes-local/src/server/execute.ts	Core execution logic: spawns hermes chat, builds prompts, parses stdout for session IDs, usage, and cost. Comment references PR #3208 but the PR description cites #3255 for the --source tool feature.
packages/adapters/hermes-local/src/ui/parse-stdout.ts	Parses Hermes stdout lines into TranscriptEntry objects (tool_call/tool_result pairs, assistant messages, system lines). Contains an unused KAOMOJI_RE constant; otherwise solid.
packages/adapters/hermes-local/src/server/detect-model.ts	Reads ~/.hermes/config.yaml with regex-based YAML parsing to extract model.default and model.provider. Error-safe (returns null on failure).
packages/adapters/hermes-local/src/server/skills.ts	Scans ~/.hermes/skills/ and merges with Paperclip-managed skills; read-only Hermes skills are correctly marked. Clean implementation.
packages/adapters/hermes-local/src/server/test.ts	Environment checks: CLI presence, version, Python ≥3.10, model config, and API keys. Fast-fails on ENOENT. Well-structured.
server/src/adapters/registry.ts	Migrates import from external hermes-paperclip-adapter to in-tree @paperclipai/adapter-hermes-local, adds listSkills/syncSkills, and wires up detectModel. Clean migration.
server/src/routes/agents.ts	Adds GET /companies/:companyId/adapters/:type/detect-model endpoint with company-access guard. detectModel is error-safe internally so no try/catch needed at the route level.
ui/src/components/AgentConfigForm.tsx	Adds Hermes to the enabled-adapters set, wires detectModel query, and extends ModelDropdown with creatable free-text input and a 'Detect from Hermes config' button. Logic is correct; no visual screenshots provided.
ui/src/adapters/hermes-local/config-fields.tsx	Renders an 'Agent instructions file' field for the Hermes adapter config form. Mirrors pattern from other adapters.
packages/adapters/hermes-local/src/index.ts	Exports adapter type, label, empty models list, and a comprehensive agentConfigurationDoc. Contains a duplicate JSDoc block for the models export.
ui/src/components/HermesIcon.tsx	Custom SVG caduceus icon for the Hermes adapter. Clean, self-contained component.

Comments Outside Diff (4)

1. packages/adapters/hermes-local/src/ui/parse-stdout.ts, line 1511-1512 (link)

   Unused KAOMOJI_RE constant

   KAOMOJI_RE is declared at the module level but is never referenced. The stripKaomoji helper uses its own inline regex instead:

   // actual usage in stripKaomoji():
   return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();

   Remove KAOMOJI_RE to avoid confusion.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/adapters/hermes-local/src/ui/parse-stdout.ts
   Line: 1511-1512
   
   Comment:
   **Unused `KAOMOJI_RE` constant**
   
   `KAOMOJI_RE` is declared at the module level but is never referenced. The `stripKaomoji` helper uses its own inline regex instead:
   
   ```ts
   // actual usage in stripKaomoji():
   return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();
   ```
   
   Remove `KAOMOJI_RE` to avoid confusion.
   
   How can I resolve this? If you propose a fix, please make it concise.

2. packages/adapters/hermes-local/src/ui/post-process.ts, line 2032-2041 (link)

   Both branches of the if/else in normalizeHermesTableBlock do the same thing

   The trailing-delimiter-stripping loop has a dead conditional:

   while (lines.length >= 2) {
     const last = lines[lines.length - 1].trim();
     if (!isDelimiterOnlyRow(last)) break;
     const prev = lines[lines.length - 2].trim();
     if (!isDelimiterOnlyRow(prev)) {
       lines.pop();           // ← pop
     } else {
       lines.pop();           // ← also pop
     }
   }

   Both branches call lines.pop(), so the if (!isDelimiterOnlyRow(prev)) check has no effect. If the intention was to stop popping once only delimiter rows remain, the logic needs to be revisited. Simplify or fix:

   while (lines.length >= 2) {
     const last = lines[lines.length - 1].trim();
     if (!isDelimiterOnlyRow(last)) break;
     lines.pop();
   }

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/adapters/hermes-local/src/ui/post-process.ts
   Line: 2032-2041
   
   Comment:
   **Both branches of the `if/else` in `normalizeHermesTableBlock` do the same thing**
   
   The trailing-delimiter-stripping loop has a dead conditional:
   
   ```ts
   while (lines.length >= 2) {
     const last = lines[lines.length - 1].trim();
     if (!isDelimiterOnlyRow(last)) break;
     const prev = lines[lines.length - 2].trim();
     if (!isDelimiterOnlyRow(prev)) {
       lines.pop();           // ← pop
     } else {
       lines.pop();           // ← also pop
     }
   }
   ```
   
   Both branches call `lines.pop()`, so the `if (!isDelimiterOnlyRow(prev))` check has no effect. If the intention was to stop popping once only delimiter rows remain, the logic needs to be revisited. Simplify or fix:
   
   ```ts
   while (lines.length >= 2) {
     const last = lines[lines.length - 1].trim();
     if (!isDelimiterOnlyRow(last)) break;
     lines.pop();
   }
   ```
   
   How can I resolve this? If you propose a fix, please make it concise.

3. packages/adapters/hermes-local/src/server/execute.ts, line 706-709 (link)

   PR reference in comment doesn't match PR description

   The inline comment attributes the --source tool flag to PR #3208, but the PR description cites #3255. Aligning these avoids future confusion about the minimum required Hermes version.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/adapters/hermes-local/src/server/execute.ts
   Line: 706-709
   
   Comment:
   **PR reference in comment doesn't match PR description**
   
   The inline comment attributes the `--source tool` flag to PR #3208, but the PR description cites #3255. Aligning these avoids future confusion about the minimum required Hermes version.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

4. packages/adapters/hermes-local/src/index.ts, line 183-193 (link)

   Duplicate JSDoc block for models

   There are two consecutive JSDoc comments for the models export — the first (lines 183–187) is immediately overwritten by the second (lines 188–192). Remove the stale one.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/adapters/hermes-local/src/index.ts
   Line: 183-193
   
   Comment:
   **Duplicate JSDoc block for `models`**
   
   There are two consecutive JSDoc comments for the `models` export — the first (lines 183–187) is immediately overwritten by the second (lines 188–192). Remove the stale one.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/ui/post-process.ts
Line: 1-10

Comment:
**Dead code — `postProcessMessage` is never called**

`postProcessMessage` is defined and exported from this 296-line file, but it is not re-exported from `src/ui/index.ts` and is not referenced anywhere else in the codebase (verified by searching the entire repo). The `UIAdapterModule` registered at `ui/src/adapters/hermes-local/index.ts` has no field for a post-processor, so this module ships as dead code:

```ts
// src/ui/index.ts — postProcessMessage is absent:
export { parseHermesStdoutLine } from "./parse-stdout.js";
export { buildHermesConfig }     from "./build-config.js";
```

Either wire it up (e.g. export it and pass it to the `UIAdapterModule` if the platform supports it) or remove the file until it is needed.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/ui/parse-stdout.ts
Line: 1511-1512

Comment:
**Unused `KAOMOJI_RE` constant**

`KAOMOJI_RE` is declared at the module level but is never referenced. The `stripKaomoji` helper uses its own inline regex instead:

```ts
// actual usage in stripKaomoji():
return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();
```

Remove `KAOMOJI_RE` to avoid confusion.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/ui/post-process.ts
Line: 2032-2041

Comment:
**Both branches of the `if/else` in `normalizeHermesTableBlock` do the same thing**

The trailing-delimiter-stripping loop has a dead conditional:

```ts
while (lines.length >= 2) {
  const last = lines[lines.length - 1].trim();
  if (!isDelimiterOnlyRow(last)) break;
  const prev = lines[lines.length - 2].trim();
  if (!isDelimiterOnlyRow(prev)) {
    lines.pop();           // ← pop
  } else {
    lines.pop();           // ← also pop
  }
}
```

Both branches call `lines.pop()`, so the `if (!isDelimiterOnlyRow(prev))` check has no effect. If the intention was to stop popping once only delimiter rows remain, the logic needs to be revisited. Simplify or fix:

```ts
while (lines.length >= 2) {
  const last = lines[lines.length - 1].trim();
  if (!isDelimiterOnlyRow(last)) break;
  lines.pop();
}
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/server/execute.ts
Line: 706-709

Comment:
**PR reference in comment doesn't match PR description**

The inline comment attributes the `--source tool` flag to PR #3208, but the PR description cites #3255. Aligning these avoids future confusion about the minimum required Hermes version.

```suggestion
  // Tag sessions as "tool" source so they don't clutter the user's session history.
  // Requires hermes-agent >= 2026.03 (NousResearch/hermes-agent#3255).
  args.push("--source", "tool");
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/index.ts
Line: 183-193

Comment:
**Duplicate JSDoc block for `models`**

There are two consecutive JSDoc comments for the `models` export — the first (lines 183–187) is immediately overwritten by the second (lines 188–192). Remove the stale one.

```suggestion
/**
 * Hermes supports any model via any provider — no fixed list.
 * The UI uses detectModel() to show the user's current config
 * and allows free-text input for any model ID.
 */
export const models: { id: string; label: string }[] = [];
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat: migrate Hermes adapter in-tree as ..." | Re-trigger Greptile}

[greptile-apps]

Dead code — postProcessMessage is never called

postProcessMessage is defined and exported from this 296-line file, but it is not re-exported from src/ui/index.ts and is not referenced anywhere else in the codebase (verified by searching the entire repo). The UIAdapterModule registered at ui/src/adapters/hermes-local/index.ts has no field for a post-processor, so this module ships as dead code:

// src/ui/index.ts — postProcessMessage is absent:
export { parseHermesStdoutLine } from "./parse-stdout.js";
export { buildHermesConfig }     from "./build-config.js";

Either wire it up (e.g. export it and pass it to the UIAdapterModule if the platform supports it) or remove the file until it is needed.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/adapters/hermes-local/src/ui/post-process.ts
Line: 1-10

Comment:
**Dead code — `postProcessMessage` is never called**

`postProcessMessage` is defined and exported from this 296-line file, but it is not re-exported from `src/ui/index.ts` and is not referenced anywhere else in the codebase (verified by searching the entire repo). The `UIAdapterModule` registered at `ui/src/adapters/hermes-local/index.ts` has no field for a post-processor, so this module ships as dead code:

```ts
// src/ui/index.ts — postProcessMessage is absent:
export { parseHermesStdoutLine } from "./parse-stdout.js";
export { buildHermesConfig }     from "./build-config.js";
```

Either wire it up (e.g. export it and pass it to the `UIAdapterModule` if the platform supports it) or remove the file until it is needed.

How can I resolve this? If you propose a fix, please make it concise.

[yepyhun]

Very good! please pull it ASAP!

[HenkDz]

ok Stuck in a loop:
Adding a new workspace package creates an unavoidable conflict between the policy and verify jobs. The verify job needs [pnpm-lock.yaml updated for @paperclipai/adapter-hermes-local, but the policy job blocks lockfile changes in PRs. The lockfile was regenerated with pnpm install --lockfile-only using pnpm 9.15.4 (matching CI).

A maintainer will need to bypass the policy check — all other jobs (verify, typecheck, build, tests) should pass with the lockfile included.

[cryppadotta]

just remove the pnpm-lock from this commit and it looks good

[cryppadotta]

Have you coordinated with NousResearch and @teknium1 on this?

Just realizing this doesn't use the upstream package. Is there a good reason to not submit this upstream to https://github.com/NousResearch/hermes-paperclip-adapter

i'm not against bringing this into paperclip i guess, it just means we're now responsible for maintaining the hermes-paperclip-adapter. hermes is great so maybe it's not a problem, but i'd want to coordinate with Nous/teknium and make sure they know we were first-partying the adapter -- but that removes control from them

if we do this we'd need to notify the upstream repo it's moving to paperclip core

[cryppadotta]

my ideal situation is that you split this into two prs

1. upstream to the original hermes adapter AND they merge your PR
2. changes you need to support it from the paperclip core as a separate PR

though if there are changes in #2 i'm curious what we have wrong in the plugin architecture such that any upstream changes to paperclip are necessary -- ideally you shouldn't have to have any pulls into paperclip to get an adapter working