# hermes-paperclip-adapter Setup and Usage

> hermes-paperclip-adapter connects Hermes Agent to Paperclip for scheduled issue work, comment-triggered wakes, structured transcripts, and persistent sessions. It suits existing Paperclip operators, not users seeking a standalone agent runtime.

**NousResearch/hermes-paperclip-adapter** — Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company

- Repository: https://github.com/NousResearch/hermes-paperclip-adapter
- Stars: 2,040 · Forks: 400
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nousresearch-hermes-paperclip-adapter

## The Paperclip Boundary for Hermes Agent

hermes-paperclip-adapter is a TypeScript integration layer between Paperclip and Hermes Agent. Paperclip supplies the company context, such as an assigned issue, a heartbeat run, or a comment wake. The adapter passes that context to Hermes Agent and returns execution results to Paperclip. Its intended user is a Paperclip operator who wants Hermes to operate as a managed employee within a company rather than only through an interactive terminal.

The package does not replace Hermes Agent, Paperclip, or an LLM provider. Hermes Agent must be installed separately, the package must be registered in the Paperclip server, and a supported provider must be configured. The README lists Hermes Agent, Python 3.10+, and at least one LLM API key as prerequisites. The `package.json` also requires Node.js `>=20.0.0` for the adapter itself.

This separation gives the project a narrow purpose. It does not provide a web interface, model gateway, scheduler, or issue database of its own. Paperclip owns scheduling and issue context. Hermes Agent owns agent execution, tools, memory, skills, and sessions. The adapter handles the boundary between those systems. That is a sensible design for an existing Paperclip deployment, but it creates additional setup compared with installing Hermes Agent alone.

## Heartbeat Data Flow and Managed Execution

Paperclip's heartbeat scheduler initiates the documented execution flow. On each heartbeat, Hermes receives task instructions, uses its enabled tools, reports results, and persists session state when `persistSession` is enabled. The registry uses `execute` from the package's `server` export, making that function the central integration point.

The architecture identifies the execution command as `hermes chat -q`. The adapter can apply a model selection, restrict toolsets, pass extra arguments, add environment variables, and enable verbose or quiet output. It also supports an execution timeout and a grace period before `SIGKILL`. These controls matter in scheduled environments because an unattended process should not run indefinitely.

The adapter does not pass raw output through unchanged. It parses Hermes stdout into typed `TranscriptEntry` values so Paperclip can render tool cards with status icons and expand or collapse behavior. It also converts Hermes ASCII banners, setext headings, and `+--+` table borders into cleaner GitHub-flavored markdown. Known MCP initialization messages and structured logs are reclassified as benign output rather than errors. This gives operators a clearer activity record, although the README does not document the complete parsing grammar.

## Installing and Registering hermes-paperclip-adapter

Install the npm package in the environment used to build or run the Paperclip server. The README gives this command:

```bash
npm install hermes-paperclip-adapter
```

Before using it, install Hermes Agent as documented by the README and ensure Python 3.10+ and a supported model API key are available. The package itself declares Node.js `>=20.0.0` in `package.json`.

Register the adapter in `server/src/adapters/registry.ts`. The README's registry example imports the main package and the server helpers explicitly:

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

The same example registers those values under the `hermes_local` adapter type. The reader should confirm that the Paperclip server resolves the package after installation and that this exact registry name matches the adapter type used when creating an agent. The README does not document a separate adapter executable or command.

## Creating a Hermes Employee in Paperclip

After registration, create an agent in the Paperclip UI or API with adapter type `hermes_local`. The README provides this example configuration:

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

Assign a Paperclip issue to the agent. During the next documented heartbeat, Hermes receives the instructions, works through them, reports results, and retains session state when persistence is enabled. The available issue assignment and Paperclip UI are external to this repository, so the adapter cannot create or complete an issue by itself.

There is a configuration inconsistency worth resolving before deployment. The quick-start example uses `maxIterations` and `enabledToolsets`, while the configuration reference lists `toolsets` as a comma-separated string and does not list `maxIterations`. The README does not explain whether `maxIterations` is accepted by the adapter, Paperclip, or Hermes Agent. Treat that example as a starting point to verify against the installed Paperclip version, not as proof that every field is consumed by this package.

## Models, Toolsets, Skills, and Prompts

The adapter supports eight inference provider names in its feature description: Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, and MiniMax. The configuration table also lists `minimax-cn` as a provider value. The model field uses `provider/model` format, with `anthropic/claude-sonnet-4` documented as the default.

The `provider` field can be set to `auto` or to a named provider. Auto-detection is also supported through `detectModel`, which reads `~/.hermes/config.yaml` to pre-populate the UI with the user's configured model. This is configuration discovery, not model hosting. Hermes Agent still needs access to the corresponding provider credentials.

Toolsets can be restricted with the documented `toolsets` field. Available names include `terminal`, `file`, `web`, `browser`, `code_execution`, `vision`, `mcp`, `creative`, and `productivity`. Skills integration scans Paperclip-managed skills and Hermes-native skills under `~/.hermes/skills/`, with `listSkills`, `syncSkills`, and `resolve` APIs. The `promptTemplate` can reference Paperclip run data such as `{{agentId}}`, `{{taskId}}`, `{{taskBody}}`, `{{commentId}}`, and `{{wakeReason}}`. Conditional blocks include `{{#taskId}}`, `{{#noTask}}`, and `{{#commentId}}`.

## Sessions, Comments, Checkpoints, and Operational Limits

Session persistence is enabled by default. Hermes state can therefore survive across Paperclip heartbeats, which supports continuity when the same agent handles related issues. The adapter includes a session codec for structured validation and migration of session state, and sessions are tagged as source `tool` so they do not clutter interactive history. The README does not specify the session database format, retention policy, or the exact migration compatibility range, so those details require verification in the relevant Hermes and Paperclip components.

Comments can trigger wakes in addition to task assignments. This is useful for follow-up instructions or feedback on an existing issue. A custom `promptTemplate` can expose `{{commentId}}` and `{{wakeReason}}`, but the README does not document deduplication or behavior when multiple comments arrive concurrently.

Optional filesystem checkpoints are disabled by default and enabled with `--checkpoints`, according to the feature list. They are described as rollback safety, but the README does not specify storage location, retention, or recovery steps. A related limitation is `worktreeMode`. It defaults to `false` and can enable Git worktree isolation, which may be appropriate for parallel code changes but adds Git and workspace assumptions. The adapter also permits arbitrary `extraArgs` and `env` values. Those settings can change execution behavior, so an operator should review them before enabling unattended access.

## hermes-paperclip-adapter Versus Direct Hermes Use

Direct Hermes Agent use is the relevant alternative for interactive, local work. Hermes can be installed and used without Paperclip, with its own tools, skills, memory, sessions, and provider configuration. That approach avoids a server registry, heartbeat scheduler, issue integration, and Paperclip session mapping.

hermes-paperclip-adapter adds a different operating model. It connects task and comment context to scheduled execution, returns structured results to Paperclip, and exposes skill synchronization and model detection to the server. It is the better fit when work needs assignment, recurring heartbeats, or visibility in Paperclip. Direct Hermes is simpler when the operator only needs a local agent session and does not need Paperclip as the control plane.

The trade-off is coupling. The adapter depends on the Paperclip registry and the installed Hermes CLI. A missing binary, incompatible registry entry, unavailable provider key, or unsupported workspace permission can prevent the scheduled workflow from completing. The README does not document compatibility versions between `hermes-paperclip-adapter` and Paperclip, so adoption should begin with the exact server and Hermes versions under consideration.

## Conclusion

Adopt hermes-paperclip-adapter if you already operate Paperclip, run Hermes Agent locally, and need managed issue execution with retained session state. Do not treat it as a standalone agent installation because it depends on Hermes Agent, Paperclip server registration, and a supported model credential. Verify the adapter registry entry, provider configuration, enabled toolsets, workspace permissions, and session storage before assigning production work. The repository's last push was on 2026-04-04, and the absence of GitHub releases leaves upgrade planning to repository and package changes.

## FAQ

### How do I install hermes-paperclip-adapter?

Install it with `npm install hermes-paperclip-adapter`. Hermes Agent must also be installed, with Python 3.10+, and the package requires Node.js `>=20.0.0`.

### How do I run Hermes Agent as a Paperclip employee?

Register the package in Paperclip's `server/src/adapters/registry.ts`, then create an agent with adapter type `hermes_local` and assign Paperclip issues to it.

### Does hermes-paperclip-adapter persist sessions across heartbeats?

Yes, `persistSession` defaults to `true`. The adapter also provides a session codec for validation and migration of session state.

### Which toolsets can Hermes use through the adapter?

The documented toolsets are `terminal`, `file`, `web`, `browser`, `code_execution`, `vision`, `mcp`, `creative`, and `productivity`. The configuration reference uses a comma-separated `toolsets` field to restrict them.

### What maintenance information is available for hermes-paperclip-adapter?

The repository is not archived, but its last push was on 2026-04-04 and it has no GitHub releases. The README does not document a release or upgrade policy.

## Sources

- [Issues](https://github.com/NousResearch/hermes-paperclip-adapter/issues)
- [License: MIT](https://github.com/NousResearch/hermes-paperclip-adapter/blob/main/LICENSE)
- [NousResearch/hermes-paperclip-adapter on GitHub](https://github.com/NousResearch/hermes-paperclip-adapter)
- [README](https://github.com/NousResearch/hermes-paperclip-adapter/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nousresearch-hermes-paperclip-adapter