NousResearch/hermes-paperclip-adapter

NousResearch/hermes-paperclip-adapter

Description: Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company

Language: TypeScript

License: MIT

Stars: 1557

Forks: 302

Open issues: 132

Created: 2026-03-11T00:16:55Z

Pushed: 2026-04-04T05:44:23Z

Default branch: main

Fork: no

Archived: no

README:

Paperclip Adapter for Hermes Agent

A Paperclip adapter that lets you run Hermes Agent as a managed employee in a Paperclip company.

Hermes Agent is a full-featured AI agent by Nous Research with 30+ native tools, persistent memory, session persistence, 80+ skills, MCP support, and multi-provider model access.

Key Features

This adapter provides:

• 8 inference providers — Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax
• Skills integration — Scans both Paperclip-managed and Hermes-native skills (~/.hermes/skills/), with sync/list/resolve APIs
• Structured transcript parsing — Raw Hermes stdout is parsed into typed TranscriptEntry objects so Paperclip renders proper tool cards with status icons and expand/collapse
• Rich post-processing — Converts Hermes ASCII banners, setext headings, and +--+ table borders into clean GFM markdown
• Comment-driven wakes — Agents wake to respond to issue comments, not just task assignments
• Auto model detection — Reads ~/.hermes/config.yaml to pre-populate the UI with the user's configured model
• Session codec — Structured validation and migration of session state across heartbeats
• Benign stderr reclassification — MCP init messages and structured logs are reclassified so they don't appear as errors in the UI
• Session source tagging — Sessions are tagged as tool source so they don't clutter the user's interactive history
• Filesystem checkpoints — Optional --checkpoints for rollback safety
• Thinking effort control — Passes --reasoning-effort for thinking/reasoning models

Hermes Agent Capabilities

| Feature | Claude Code | Codex | Hermes Agent | |---------|------------|-------|-------------| | Persistent memory | ❌ | ❌ | ✅ Remembers across sessions | | Native tools | ~5 | ~5 | 30+ (terminal, file, web, browser, vision, git, etc.) | | Skills system | ❌ | ❌ | ✅ 80+ loadable skills | | Session search | ❌ | ❌ | ✅ FTS5 search over past conversations | | Sub-agent delegation | ❌ | ❌ | ✅ Parallel sub-tasks | | Context compression | ❌ | ❌ | ✅ Auto-compresses long conversations | | MCP client | ❌ | ❌ | ✅ Connect to any MCP server | | Multi-provider | Anthropic only | OpenAI only | ✅ 8 providers out of the box |

Installation

npm install hermes-paperclip-adapter

Prerequisites

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

Quick Start

1. Register the adapter in your Paperclip server

Add to your Paperclip server's adapter registry (server/src/adapters/registry.ts):

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,
});

2. Create a Hermes agent in Paperclip

In the Paperclip UI or via API, create an agent with adapter type hermes_local:

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

3. Assign work

Create issues in Paperclip and assign them to your Hermes agent. On each heartbeat, Hermes will:

1. Receive the task instructions 2. Use its full tool suite to complete the work 3. Report results back to Paperclip 4. Persist session state for continuity

Configuration Reference

Core

| Field | Type | Default | Description | |-------|------|---------|-------------| | model | string | anthropic/claude-sonnet-4 | Model in provider/model format | | provider | string | *(auto-detected)* | API provider: auto, openrouter, nous, openai-codex, zai, kimi-coding, minimax, minimax-cn | | timeoutSec | number | 300 | Execution timeout in seconds | | graceSec | number | 10 | Grace period before SIGKILL |

Tools

| Field | Type | Default | Description | |-------|------|---------|-------------| | toolsets | string | *(all)* | Comma-separated toolsets to enable (e.g. "terminal,file,web") |

Available toolsets: terminal, file, web, browser, code_execution, vision, mcp, creative, productivity

Session & Workspace

| Field | Type | Default | Description | |-------|------|---------|-------------| | persistSession | boolean | true | Resume sessions across heartbeats | | worktreeMode | boolean | false | Git worktree isolation | | checkpoints | boolean | false | Enable filesystem checkpoints for rollback |

Advanced

| Field | Type | Default | Description | |-------|------|---------|-------------| | hermesCommand | string | hermes | Custom CLI binary path | | verbose | boolean | false | Enable verbose output | | quiet | boolean | true | Quiet mode (clean output, no banner/spinner) | | extraArgs | string[] | [] | Additional CLI arguments | | env | object | {} | Extra environment variables | | promptTemplate | string | *(built-in)* | Custom prompt template | | paperclipApiUrl | string | http://127.0.0.1:3100/api | Paperclip API base URL |

Prompt Template Variables

Use {{variable}} syntax in promptTemplate:

| Variable | Description | |----------|-------------| | {{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:

-…