undefined

undefined

npm install hermes-paperclip-adapter

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

// In your registry setup
registry.set("hermes_local", {
  ...hermesLocal,
  execute,
  testEnvironment,
  detectModel,
  listSkills,
  syncSkills,
  sessionCodec,
});

const agentConfig = {
  name: "Hermes Engineer",
  adapterType: "hermes_local",
  adapterConfig: {
    // Model selection (provider/model format)
    model: "anthropic/claude-sonnet-4",
    
    // Execution limits
    maxIterations: 50,
    timeoutSec: 300,
    graceSec: 10,
    
    // Session persistence
    persistSession: true,
    
    // Tool control
    enabledToolsets: ["terminal", "file", "web", "browser"],
    
    // Workspace isolation
    worktreeMode: false,
    checkpoints: false,
    
    // Output control
    verbose: false,
    quiet: true
  }
};

// Anthropic
{ model: "anthropic/claude-sonnet-4" }
{ model: "anthropic/claude-opus-4" }

// OpenRouter
{ model: "openrouter/anthropic/claude-3.5-sonnet" }
{ model: "openrouter/deepseek/deepseek-chat" }

// OpenAI
{ model: "openai/gpt-4" }
{ model: "openai/o1" }

// Nous
{ model: "nous/hermes-3" }

// Explicit provider override
{ 
  model: "claude-sonnet-4",
  provider: "anthropic"
}

export ANTHROPIC_API_KEY=sk-ant-...
export OPENROUTER_API_KEY=sk-or-...
export OPENAI_API_KEY=sk-...
export NOUS_API_KEY=...

{
  // Only terminal, file, and web tools
  enabledToolsets: ["terminal", "file", "web"]
}

{
  // Enable MCP and vision
  enabledToolsets: ["mcp", "vision"]
}

{
  // Empty = all tools enabled (default)
  enabledToolsets: []
}

{
  promptTemplate: `You are {{agentName}}, an AI engineer working for {{companyName}}.

{{#taskId}}

Available variables:
- `{{agentId}}`, `{{agentName}}`
- `{{companyId}}`, `{{companyName}}`
- `{{runId}}`, `{{taskId}}`, `{{taskTitle}}`, `{{taskBody}}`
- `{{projectName}}`, `{{commentId}}`, `{{wakeReason}}`
- `{{paperclipApiUrl}}`

Conditionals:
- `{{#taskId}}...{{/taskId}}` — only when task assigned
- `{{#noTask}}...{{/noTask}}` — only when no task
- `{{#commentId}}...{{/commentId}}` — only when woken by comment

import { PaperclipClient } from "paperclip-client";

const client = new PaperclipClient({
  apiUrl: process.env.PAPERCLIP_API_URL,
  apiKey: process.env.PAPERCLIP_API_KEY
});

// Create agent
const agent = await client.agents.create({
  name: "Hermes DevOps",
  adapterType: "hermes_local",
  adapterConfig: {
    model: "anthropic/claude-sonnet-4",
    maxIterations: 50,
    timeoutSec: 600,
    persistSession: true,
    enabledToolsets: ["terminal", "file", "web"],
    env: {
      // Custom env vars for Hermes
      HERMES_LOG_LEVEL: "info"
    }
  },
  schedule: {
    cron: "*/15 * * * *" // Check every 15 minutes
  }
});

console.log(`Created agent: ${agent.id}`);

// Create an issue
const issue = await client.issues.create({
  title: "Optimize database queries",
  body: `Review the API endpoint /api/users and optimize the database queries.
  
Current query time is ~500ms, target is <100ms.
  
Files:
- src/api/users.ts
- src/db/queries/users.ts
  
Run benchmarks before and after changes.`,
  projectId: "proj_123"
});

// Assign to Hermes
await client.issues.assign({
  issueId: issue.id,
  agentId: agent.id
});

// Get run details
const run = await client.runs.get(runId);

console.log(`Status: ${run.status}`);
console.log(`Model: ${run.modelUsed}`);
console.log(`Tokens: ${run.tokenUsage.total}`);
console.log(`Cost: $${run.cost}`);
console.log(`Session: ${run.sessionId}`);

// View transcript
for (const entry of run.transcript) {
  console.log(`[${entry.type}] ${entry.content}`);
  
  if (entry.type === "tool_use") {
    console.log(`  Tool: ${entry.toolName}`);
    console.log(`  Status: ${entry.status}`);
  }
}

import { listSkills, syncSkills } from "hermes-paperclip-adapter/server";

// List all available skills
const skills = await listSkills({
  agentId: "agent_123",
  companyId: "company_456"
});

console.log("Paperclip-managed skills:", skills.managed.length);
console.log("Hermes-native skills:", skills.native.length);

// Sync skills from Paperclip to Hermes workspace
await syncSkills({
  agentId: "agent_123",
  companyId: "company_456",
  enabledSkills: ["typescript-expert", "postgres-tuning", "docker-ops"]
});

import { testEnvironment } from "hermes-paperclip-adapter/server";

const check = await testEnvironment({
  hermesCommand: "hermes",
  provider: "anthropic",
  env: {
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY
  }
});

if (!check.success) {
  console.error("Environment issues:", check.errors);
  // Example errors:
  // - "Hermes CLI not found in PATH"
  // - "Python version 3.10+ required"
  // - "ANTHROPIC_API_KEY not set"
}

import { detectModel } from "hermes-paperclip-adapter/server";

// Reads ~/.hermes/config.yaml to pre-populate UI
const detected = await detectModel({
  hermesCommand: "hermes"
});

console.log(`Default model: ${detected.model}`);
console.log(`Provider: ${detected.provider}`);

import { sessionCodec } from "hermes-paperclip-adapter/server";

// Validate and migrate session state
const validated = sessionCodec.decode(rawSessionState);

if (validated._tag === "Right") {
  const session = validated.right;
  console.log(`Session ID: ${session.sessionId}`);
  console.log(`Messages: ${session.messageCount}`);
  console.log(`Last activity: ${session.lastActivity}`);
} else {
  console.error("Invalid session state:", validated.left);
}

{
  worktreeMode: true,
  // Each run gets: repo/.paperclip/worktrees/agent_123/run_456
}

{
  checkpoints: true,
  // Creates snapshots before destructive operations
}

{
  model: "openai/o1",
  extraArgs: ["--reasoning-effort", "high"]
}

{
  hermesCommand: "/usr/local/bin/hermes-dev",
  verbose: true
}

{
  env: {
    HERMES_LOG_LEVEL: "debug",
    HERMES_CACHE_DIR: "/mnt/fast-storage/hermes-cache",
    MCP_SERVER_URL: "http://localhost:8080"
  }
}

type TranscriptEntry = 
  | { type: "message"; role: "user" | "assistant"; content: string }
  | { type: "tool_use"; toolName: string; status: "running" | "success" | "error"; input: any; output?: any }
  | { type: "thinking"; content: string }
  | { type: "memory_write"; key: string; value: any }
  | { type: "error"; message: string; stderr?: string };

// Example parsed output
[
  { type: "message", role: "user", content: "Optimize the database queries" },
  { type: "tool_use", toolName: "read_file", status: "success", input: { path: "src/api/users.ts" } },
  { type: "thinking", content: "The current query uses a full table scan..." },
  { type: "tool_use", toolName: "run_command", status: "running", input: { command: "npm run benchmark" } },
  { type: "tool_use", toolName: "run_command", status: "success", output: "Average: 487ms" },
  { type: "memory_write", key: "baseline_perf", value: "487ms" },
  { type: "message", role: "assistant", content: "I've added an index on user_id..." }
]

╔═══════════════════════════════════════╗
║       HERMES AGENT v2.1.0             ║
╚═══════════════════════════════════════╝

Results
=======

+---------------------------+----------+
| Metric                    | Value    |
+---------------------------+----------+
| Query time (before)       | 487ms    |
| Query time (after)        | 83ms     |
+---------------------------+----------+

undefined

undefined

undefined

undefined

undefined

undefined

// Disable persistence for debugging
{
  persistSession: false
}

// Check session state
const run = await client.runs.get(runId);
console.log("Session state:", run.sessionState);

// Increase timeout for long-running tasks
{
  timeoutSec: 1800, // 30 minutes
  graceSec: 30,
  maxIterations: 100
}

// Check which tools are enabled
{
  enabledToolsets: ["terminal", "file"], // Minimal set
  verbose: true // See tool invocations
}

// Use quiet mode to suppress MCP init messages
{
  quiet: true
}

// Benign stderr patterns are auto-reclassified:
// - "MCP server initialized"
// - JSON structured logs
// - Progress indicators

undefined

undefined

// Context compression is automatic, but you can control it:
{
  extraArgs: [
    "--context-window", "200000",
    "--compress-after", "150000"
  ]
}

name: Paperclip Hermes Agent

on:
  schedule:
    - cron: '*/30 * * * *'

jobs:
  hermes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install Hermes
        run: pip install hermes-agent
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Trigger Paperclip Heartbeat
        run: |
          curl -X POST ${{ secrets.PAPERCLIP_API_URL }}/agents/${{ secrets.AGENT_ID }}/heartbeat \
            -H "Authorization: Bearer ${{ secrets.PAPERCLIP_API_KEY }}"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

FROM node:20-slim

undefined

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hermes-agent
spec:
  schedule: "*/15 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hermes
            image: paperclip/hermes-agent:latest
            env:
            - name: ANTHROPIC_API_KEY
              valueFrom:
                secretKeyRef:
                  name: api-keys
                  key: anthropic
            - name: PAPERCLIP_API_URL
              value: "http://paperclip-server:3100/api"
          restartPolicy: OnFailure