{"_id":"hermes-paperclip-adapter","_rev":"5-ce06f11c2668df62d65860aee04fe87d","name":"hermes-paperclip-adapter","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"hermes-paperclip-adapter","version":"0.1.0","keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"author":{"name":"Nous Research"},"license":"MIT","_id":"hermes-paperclip-adapter@0.1.0","maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"dist":{"shasum":"5d70f63b31fec61ca03f52b279eabe6ba94c6e71","tarball":"https://registry.npmjs.org/hermes-paperclip-adapter/-/hermes-paperclip-adapter-0.1.0.tgz","fileCount":43,"integrity":"sha512-g8o/etN/wtt9cnrvqsWWYrqL8toXepAv2IPJjZQFibD/UAICuAIoyl2hSahrs3sC3YUi6GeFKF5mP//m7LFF7g==","signatures":[{"sig":"MEUCIQCtw2vRv8OUrXYV/frma56g6K4k+0S58ubCWaycW5yFVwIgJ2JCZq2zBxmAnmxw861+491xceY1qGvL5cRsbh8g/8g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73999},"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./dist/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js","./server":"./dist/server/index.js"},"gitHead":"05e519a642b90194bce8cafe6b593c70dabfe420","scripts":{"dev":"tsc --watch","lint":"eslint src/","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"teknium","email":"teknium1@gmail.com"},"repository":{"url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git","type":"git"},"_npmVersion":"10.8.2","description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","directories":{},"_nodeVersion":"20.20.0","dependencies":{"picocolors":"^1.1.0","@paperclipai/adapter-utils":"^0.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hermes-paperclip-adapter_0.1.0_1773361384208_0.21611810958829003","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"hermes-paperclip-adapter","version":"0.1.1","keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"author":{"name":"Nous Research"},"license":"MIT","_id":"hermes-paperclip-adapter@0.1.1","maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"dist":{"shasum":"df7cb38fd1093d18924b3f121faea58756659794","tarball":"https://registry.npmjs.org/hermes-paperclip-adapter/-/hermes-paperclip-adapter-0.1.1.tgz","fileCount":43,"integrity":"sha512-kbdX349VxExSkVL8n4RwTpP9fUBf2yWpsTsJp02X12A9NynRJatlpYqt0vEkFyE/X7qEXqdJvpBm9tlvUHahsA==","signatures":[{"sig":"MEUCIQDIWxTjWNgPDITpD45QkgMP1gWEYlESA78aJ/TRFt2A1gIgCmifSPTSrP/I0iFF5K2NAD5qX8MEBmvf5pHh/OaFiVI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74160},"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./dist/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js","./server":"./dist/server/index.js"},"gitHead":"e2cdafa7f86c1f3b994c9748479cc1349d7b9720","scripts":{"dev":"tsc --watch","lint":"eslint src/","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"teknium","email":"teknium1@gmail.com"},"repository":{"url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git","type":"git"},"_npmVersion":"10.8.2","description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","directories":{},"_nodeVersion":"20.20.0","dependencies":{"picocolors":"^1.1.0","@paperclipai/adapter-utils":"^0.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hermes-paperclip-adapter_0.1.1_1773362083936_0.2669273951442803","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"hermes-paperclip-adapter","version":"0.2.0","keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"author":{"name":"Nous Research"},"license":"MIT","_id":"hermes-paperclip-adapter@0.2.0","maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"dist":{"shasum":"1460edef34074d3bf969fbef6ad4357c7f02dcdc","tarball":"https://registry.npmjs.org/hermes-paperclip-adapter/-/hermes-paperclip-adapter-0.2.0.tgz","fileCount":51,"integrity":"sha512-6CP5vxfvY4jY9XJK5zu4ZUL9aB7HHNtEMk6q7m1Pu9Gzoby1Vx5VNmVqte3NUO+1cvVK9Arj1f67xLagWkbo5Q==","signatures":[{"sig":"MEUCIGXjpKZunFlM3+lZObDSOvHSVNxjxUnqQa9dR09rgYM0AiEAyl6tAr1aRSy44llpJT+lW8TE74pzD8tFFzfdxFMyP88=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":117183},"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./dist/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js","./server":"./dist/server/index.js"},"gitHead":"aeeeb0451f5c85f219ee75584e80897458c3630f","scripts":{"dev":"tsc --watch","lint":"eslint src/","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"teknium","email":"teknium1@gmail.com"},"repository":{"url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git","type":"git"},"_npmVersion":"10.8.2","description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","directories":{},"_nodeVersion":"20.20.0","dependencies":{"picocolors":"^1.1.0","@paperclipai/adapter-utils":"^2026.325.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hermes-paperclip-adapter_0.2.0_1774661480422_0.7408110760812059","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"hermes-paperclip-adapter","version":"0.2.1","keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"author":{"name":"Nous Research"},"license":"MIT","_id":"hermes-paperclip-adapter@0.2.1","maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"dist":{"shasum":"9f13e9c246ca8d24951bc9c6a7e681e4e54a664b","tarball":"https://registry.npmjs.org/hermes-paperclip-adapter/-/hermes-paperclip-adapter-0.2.1.tgz","fileCount":51,"integrity":"sha512-9D4SrmMXm4AhOZ08lnlGCZBzwfRnGjzZjkvPlkRfoPTODM2YeIAaEk+zO0vInh8DI4Qr3ySN8hLFxV1eKRYFaA==","signatures":[{"sig":"MEUCIQCrEjvXPGdvrFWRz4ceUCo/6zj+fkW/LJfJLzOFr4p0VAIgcwgWrzrRTy85PS5J61DQjC0vtMjEmUSSHJObZyx9PVs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":134872},"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./dist/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js","./server":"./dist/server/index.js"},"gitHead":"5eaf757e0b9987e3d4f404085a4a24919eaf3820","scripts":{"dev":"tsc --watch","lint":"eslint src/","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"teknium","email":"teknium1@gmail.com"},"repository":{"url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git","type":"git"},"_npmVersion":"10.8.2","description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","directories":{},"_nodeVersion":"20.20.0","dependencies":{"picocolors":"^1.1.0","@paperclipai/adapter-utils":"^2026.325.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hermes-paperclip-adapter_0.2.1_1774860737387_0.7669418562439081","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"hermes-paperclip-adapter","version":"0.3.0","description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","type":"module","license":"MIT","author":{"name":"Nous Research"},"repository":{"type":"git","url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git"},"keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"exports":{".":"./dist/index.js","./server":"./dist/server/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","lint":"eslint src/","typecheck":"tsc --noEmit","clean":"rm -rf dist"},"dependencies":{"@paperclipai/adapter-utils":"^2026.325.0","picocolors":"^1.1.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"engines":{"node":">=20.0.0"},"_id":"hermes-paperclip-adapter@0.3.0","gitHead":"3d25bff31f4849f170d65cbe0e10014e4ccddb06","bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-MgAM/H2Fp650RVr5E1hYat5n8FaCzvxOOjhlN98hUMS9q6M+JeLvVE8Z1LfUs8KlavCn10m+DiwBxH55m0SmHA==","shasum":"11ed6cb2dfac15aa88c5b7cfbfe3c6b349ee71d5","tarball":"https://registry.npmjs.org/hermes-paperclip-adapter/-/hermes-paperclip-adapter-0.3.0.tgz","fileCount":51,"unpackedSize":135967,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICSt3x5kO//cHYmM3pV+a7VVr+GsRCKOMc6pCIwRDsY5AiEAt8HnJAFZqIrZDRiKi0mo18rSC/IFP4PsFs8eFq/DE/I="}]},"_npmUser":{"name":"teknium","email":"teknium1@gmail.com"},"directories":{},"maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hermes-paperclip-adapter_0.3.0_1774984921561_0.06931938334725496"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-13T00:23:04.109Z","modified":"2026-03-31T19:22:01.827Z","0.1.0":"2026-03-13T00:23:04.387Z","0.1.1":"2026-03-13T00:34:44.097Z","0.2.0":"2026-03-28T01:31:20.568Z","0.2.1":"2026-03-30T08:52:17.534Z","0.3.0":"2026-03-31T19:22:01.700Z"},"bugs":{"url":"https://github.com/NousResearch/hermes-paperclip-adapter/issues"},"author":{"name":"Nous Research"},"license":"MIT","homepage":"https://github.com/NousResearch/hermes-paperclip-adapter#readme","keywords":["paperclip","hermes","hermes-agent","ai-agent","adapter","orchestration"],"repository":{"type":"git","url":"git+https://github.com/NousResearch/hermes-paperclip-adapter.git"},"description":"Paperclip adapter for Hermes Agent — run Hermes as a managed employee in a Paperclip company","maintainers":[{"name":"teknium","email":"teknium1@gmail.com"}],"readme":"# Paperclip Adapter for Hermes Agent\n\nA [Paperclip](https://paperclip.ing) adapter that lets you run [Hermes Agent](https://github.com/NousResearch/hermes-agent) as a managed employee in a Paperclip company.\n\nHermes Agent is a full-featured AI agent by [Nous Research](https://nousresearch.com) with 30+ native tools, persistent memory, session persistence, 80+ skills, MCP support, and multi-provider model access.\n\n## Key Features\n\nThis adapter provides:\n\n- **8 inference providers** — Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax\n- **Skills integration** — Scans both Paperclip-managed and Hermes-native skills (`~/.hermes/skills/`), with sync/list/resolve APIs\n- **Structured transcript parsing** — Raw Hermes stdout is parsed into typed `TranscriptEntry` objects so Paperclip renders proper tool cards with status icons and expand/collapse\n- **Rich post-processing** — Converts Hermes ASCII banners, setext headings, and `+--+` table borders into clean GFM markdown\n- **Comment-driven wakes** — Agents wake to respond to issue comments, not just task assignments\n- **Auto model detection** — Reads `~/.hermes/config.yaml` to pre-populate the UI with the user's configured model\n- **Session codec** — Structured validation and migration of session state across heartbeats\n- **Benign stderr reclassification** — MCP init messages and structured logs are reclassified so they don't appear as errors in the UI\n- **Session source tagging** — Sessions are tagged as `tool` source so they don't clutter the user's interactive history\n- **Filesystem checkpoints** — Optional `--checkpoints` for rollback safety\n- **Thinking effort control** — Passes `--reasoning-effort` for thinking/reasoning models\n\n### Hermes Agent Capabilities\n\n| Feature | Claude Code | Codex | Hermes Agent |\n|---------|------------|-------|-------------|\n| Persistent memory | ❌ | ❌ | ✅ Remembers across sessions |\n| Native tools | ~5 | ~5 | 30+ (terminal, file, web, browser, vision, git, etc.) |\n| Skills system | ❌ | ❌ | ✅ 80+ loadable skills |\n| Session search | ❌ | ❌ | ✅ FTS5 search over past conversations |\n| Sub-agent delegation | ❌ | ❌ | ✅ Parallel sub-tasks |\n| Context compression | ❌ | ❌ | ✅ Auto-compresses long conversations |\n| MCP client | ❌ | ❌ | ✅ Connect to any MCP server |\n| Multi-provider | Anthropic only | OpenAI only | ✅ 8 providers out of the box |\n\n## Installation\n\n```bash\nnpm install hermes-paperclip-adapter\n```\n\n### Prerequisites\n\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed (`pip install hermes-agent`)\n- Python 3.10+\n- At least one LLM API key (Anthropic, OpenRouter, or OpenAI)\n\n## Quick Start\n\n### 1. Register the adapter in your Paperclip server\n\nAdd to your Paperclip server's adapter registry (`server/src/adapters/registry.ts`):\n\n```typescript\nimport * as hermesLocal from \"hermes-paperclip-adapter\";\nimport {\n  execute,\n  testEnvironment,\n  detectModel,\n  listSkills,\n  syncSkills,\n  sessionCodec,\n} from \"hermes-paperclip-adapter/server\";\n\nregistry.set(\"hermes_local\", {\n  ...hermesLocal,\n  execute,\n  testEnvironment,\n  detectModel,\n  listSkills,\n  syncSkills,\n  sessionCodec,\n});\n```\n\n### 2. Create a Hermes agent in Paperclip\n\nIn the Paperclip UI or via API, create an agent with adapter type `hermes_local`:\n\n```json\n{\n  \"name\": \"Hermes Engineer\",\n  \"adapterType\": \"hermes_local\",\n  \"adapterConfig\": {\n    \"model\": \"anthropic/claude-sonnet-4\",\n    \"maxIterations\": 50,\n    \"timeoutSec\": 300,\n    \"persistSession\": true,\n    \"enabledToolsets\": [\"terminal\", \"file\", \"web\"]\n  }\n}\n```\n\n### 3. Assign work\n\nCreate issues in Paperclip and assign them to your Hermes agent. On each heartbeat, Hermes will:\n\n1. Receive the task instructions\n2. Use its full tool suite to complete the work\n3. Report results back to Paperclip\n4. Persist session state for continuity\n\n## Configuration Reference\n\n### Core\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `model` | string | `anthropic/claude-sonnet-4` | Model in `provider/model` format |\n| `provider` | string | *(auto-detected)* | API provider: `auto`, `openrouter`, `nous`, `openai-codex`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` |\n| `timeoutSec` | number | `300` | Execution timeout in seconds |\n| `graceSec` | number | `10` | Grace period before SIGKILL |\n\n### Tools\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `toolsets` | string | *(all)* | Comma-separated toolsets to enable (e.g. `\"terminal,file,web\"`) |\n\nAvailable toolsets: `terminal`, `file`, `web`, `browser`, `code_execution`, `vision`, `mcp`, `creative`, `productivity`\n\n### Session & Workspace\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `persistSession` | boolean | `true` | Resume sessions across heartbeats |\n| `worktreeMode` | boolean | `false` | Git worktree isolation |\n| `checkpoints` | boolean | `false` | Enable filesystem checkpoints for rollback |\n\n### Advanced\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `hermesCommand` | string | `hermes` | Custom CLI binary path |\n| `verbose` | boolean | `false` | Enable verbose output |\n| `quiet` | boolean | `true` | Quiet mode (clean output, no banner/spinner) |\n| `extraArgs` | string[] | `[]` | Additional CLI arguments |\n| `env` | object | `{}` | Extra environment variables |\n| `promptTemplate` | string | *(built-in)* | Custom prompt template |\n| `paperclipApiUrl` | string | `http://127.0.0.1:3100/api` | Paperclip API base URL |\n\n### Prompt Template Variables\n\nUse `{{variable}}` syntax in `promptTemplate`:\n\n| Variable | Description |\n|----------|-------------|\n| `{{agentId}}` | Paperclip agent ID |\n| `{{agentName}}` | Agent display name |\n| `{{companyId}}` | Company ID |\n| `{{companyName}}` | Company name |\n| `{{runId}}` | Current heartbeat run ID |\n| `{{taskId}}` | Assigned task/issue ID |\n| `{{taskTitle}}` | Task title |\n| `{{taskBody}}` | Task instructions |\n| `{{projectName}}` | Project name |\n| `{{paperclipApiUrl}}` | Paperclip API base URL |\n| `{{commentId}}` | Comment ID (when woken by a comment) |\n| `{{wakeReason}}` | Reason this run was triggered |\n\nConditional sections:\n\n- `{{#taskId}}...{{/taskId}}` — included only when a task is assigned\n- `{{#noTask}}...{{/noTask}}` — included only when no task (heartbeat check)\n- `{{#commentId}}...{{/commentId}}` — included only when woken by a comment\n\n## Architecture\n\n```\nPaperclip                          Hermes Agent\n┌──────────────────┐               ┌──────────────────┐\n│  Heartbeat       │               │                  │\n│  Scheduler       │───execute()──▶│  hermes chat -q  │\n│                  │               │                  │\n│  Issue System    │               │  30+ Tools       │\n│  Comment Wakes   │◀──results─────│  Memory System   │\n│                  │               │  Session DB      │\n│  Cost Tracking   │               │  Skills          │\n│                  │               │  MCP Client      │\n│  Skill Sync      │◀──snapshot────│  ~/.hermes/skills│\n│  Org Chart       │               │                  │\n└──────────────────┘               └──────────────────┘\n```\n\nThe adapter spawns Hermes Agent's CLI in single-query mode (`-q`). Hermes\nprocesses the task using its full tool suite, then exits. The adapter:\n\n1. **Captures** stdout/stderr and parses token usage, session IDs, and cost\n2. **Parses** raw output into structured `TranscriptEntry` objects (tool cards with status icons)\n3. **Post-processes** Hermes ASCII formatting (banners, setext headings, table borders) into clean GFM markdown\n4. **Reclassifies** benign stderr (MCP init, structured logs) so they don't show as errors\n5. **Tags** sessions as `tool` source to keep them separate from interactive usage\n6. **Reports** results back to Paperclip with cost, usage, and session state\n\nSession persistence works via Hermes's `--resume` flag — each run picks\nup where the last one left off, maintaining conversation context,\nmemories, and tool state across heartbeats. The `sessionCodec` validates\nand migrates session state between runs.\n\n### Skills Integration\n\nThe adapter scans two skill sources and merges them:\n\n- **Paperclip-managed skills** — bundled with the adapter, togglable from the UI\n- **Hermes-native skills** — from `~/.hermes/skills/`, read-only, always loaded\n\nThe `listSkills` / `syncSkills` APIs expose a unified snapshot so the\nPaperclip UI can display both managed and native skills in one view.\n\n## Development\n\n```bash\ngit clone https://github.com/NousResearch/hermes-paperclip-adapter\ncd hermes-paperclip-adapter\nnpm install\nnpm run build\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n## Links\n\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — The AI agent this adapter runs\n- [Paperclip](https://github.com/paperclipai/paperclip) — The orchestration platform\n- [Nous Research](https://nousresearch.com) — The team behind Hermes\n- [Paperclip Docs](https://paperclip.ing/docs) — Paperclip documentation\n","readmeFilename":"README.md"}