Paperclip Agent Adapters: Complete Guide to Built-in and Custom Configuration

Paperclip supports 11 built-in agent adapters including Claude Code, OpenAI Codex, Gemini, Cursor, and HTTP webhooks, while custom adapters can be added via npm packages or local directories without modifying core code.

Adapters are the bridge between Paperclip's orchestration layer and AI runtimes. Each adapter knows how to start a specific tool, capture its output stream, and return structured results that the platform can track, bill, and display. This guide covers every officially supported adapter and the exact steps to configure your own.

Built-in Paperclip Agent Adapters

The platform ships with stable, fully-supported adapters recognized by both the server and UI. These cover local CLI tools, remote gateways, and generic processes.

Adapter	Type Key	Runtime
Claude Code	claude_local	Anthropic Claude Code CLI (local) with native ACP engine support
Codex	codex_local	OpenAI Codex CLI (local) with ACP engine support
Gemini CLI	gemini_local	Google Gemini CLI (experimental)
OpenCode	opencode_local	Multi-provider CLI using provider/model syntax
Cursor	cursor	Cursor editor in background mode
Pi	pi_local	Embedded Pi agent (local deployment)
Hermes Local	hermes_local	Local Hermes CLI via @paperclipai/hermes-paperclip-adapter
Hermes Gateway	hermes_gateway	Remote Hermes HTTP/SSE API server
OpenClaw Gateway	openclaw_gateway	External OpenClaw gateway endpoint
Process	process	Arbitrary shell command execution
HTTP	http	Webhook calls to external agent services

Source: [docs/adapters/overview.md](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/overview.md)

How Adapters Execute at Runtime

When a heartbeat triggers an agent execution, Paperclip follows a three-step flow:

1. Lookup — Resolves the agent's adapterType and adapterConfig from its configuration
2. Execute — Calls the adapter's execute() method with the full execution context (workspace, environment, credentials)
3. Return — The adapter spawns the runtime, streams stdout/stderr, parses usage and cost data, and returns a structured ExecutionResult

This architecture keeps orchestration logic separate from runtime specifics. Each adapter handles its own process management, event parsing, and error translation.

Configuring Custom Adapters in Paperclip

External adapters let you extend Paperclip without forking the core repository. These are standard npm packages that implement the adapter contract and register through the plugin system.

Installation Methods

Method	POST Body	Use Case
NPM package	{"packageName": "my-paperclip-adapter"}	Published, versioned adapters
Local directory	{"localPath": "/home/user/my-adapter"}	Development or private adapters

Both methods call POST /api/adapters and return a registered adapter with a generated type key (typically suffixed with _local).

# Register from npm

curl -X POST http://localhost:3102/api/adapters \
  -H "Content-Type: application/json" \
  -d '{"packageName":"@myorg/my-paperclip-adapter"}'

# Register local development adapter

curl -X POST http://localhost:3102/api/adapters \
  -H "Content-Type: application/json" \
  -d '{"localPath":"/home/user/custom-adapter"}'

Source: [docs/adapters/overview.md](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/overview.md), lines 80-88

Required Adapter Package Structure

A minimal external adapter follows this exact layout:

my-adapter/
├── src/
│   ├── index.ts           # Exports: type key, label, supported models

│   ├── server/
│   │   ├── execute.ts     # Core execution logic (spawn, stream, capture)

│   │   ├── parse.ts       # Raw stdout → structured events

│   │   └── test.ts        # Runtime environment diagnostics

│   ├── ui-parser.ts       # Optional: rich UI transcript rendering

│   └── cli/
│       └── format-event.ts # Terminal output for `paperclipai run --watch`

Required exports:

• createServerAdapter() — consumed by the server registry at packages/adapter-utils/
• Optional: ui-parser.js — enables the web UI to render custom transcript formats

Source: [docs/adapters/overview.md](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/overview.md), lines 96-115

CLI Registration and Agent Assignment

The Paperclip CLI wraps the API for convenience:

# Install from npm registry

paperclipai adapters add --package my-paperclip-adapter

# Link local folder

paperclipai adapters add --local /home/user/my-adapter

After registration, create an agent referencing the generated type key:

POST /api/agents
{
  "name": "Custom-Code-Bot",
  "urlKey": "custom-bot",
  "adapterType": "myadapter_local",
  "adapterConfig": {
    "model": "gpt-4o-mini",
    "engine": "acp",
    "maxTokens": 1024
  }
}

The adapterConfig object is adapter-specific — consult each adapter's documentation for valid keys like model, engine, apiKey, or temperature.

Example Execute Implementation

From [docs/adapters/creating-an-adapter.md](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/creating-an-adapter.md), the core execute.ts skeleton:

import { ExecutionContext, ExecutionResult } from "@paperclipai/adapter-utils";
import { spawn } from "child_process";

export async function execute(ctx: ExecutionContext): Promise<ExecutionResult> {
  // Spawn the target runtime with configuration from adapterConfig
  const child = spawn("my-runtime", ["--model", ctx.config.model], {
    cwd: ctx.workspace,
    env: { ...process.env, ...ctx.env },
  });

  // Stream processing, event parsing, and result assembly
  // ...
}

Adapter Credentials and Sandbox Security

For adapters running CLI tools on remote sandboxes, credential precedence varies by implementation:

• codex_local — Prefers host-owned auth.json uploaded to the sandbox
• claude_local — Prefers per-agent ANTHROPIC_API_KEY if provided in adapterConfig

Always verify credential behavior in your specific adapter's documentation before deploying to shared infrastructure.

Source: [docs/adapters/overview.md](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/overview.md), lines 33-42

Summary

• 11 built-in adapters cover major AI platforms (Claude, Codex, Gemini, Cursor, Pi) plus generic Process and HTTP options
• Custom adapters install via POST /api/adapters with packageName or localPath — no core code changes required
• Generated type keys (e.g., myadapter_local) appear in the UI immediately after registration
• Adapter package structure requires src/index.ts with createServerAdapter() export and src/server/execute.ts for runtime logic
• adapterConfig is completely free-form per adapter — no universal schema constraints
• Credential precedence rules differ by adapter; check sandbox-specific documentation

Frequently Asked Questions

What is the fastest way to test a custom adapter during development?

Use paperclipai adapters add --local /path/to/adapter to link your adapter directory without publishing to npm. Changes to the source files require re-registration or server restart depending on your Paperclip version.

Can I override a built-in adapter with a custom implementation?

No — built-in type keys (claude_local, codex_local, etc.) are reserved. Custom adapters receive generated type keys to prevent collisions. If you need modified behavior, register under a new name and migrate agents manually.

Where does Paperclip store adapter utilities for workspace and SSH handling?

The @paperclipai/adapter-utils package in packages/adapter-utils/ exports helpers like prepareWorkspaceForSshExecution() and restoreWorkspaceFromSshExecution() that external adapters should use for safe workspace transfers.

Do custom adapters require TypeScript?

TypeScript is strongly recommended for type safety against the ExecutionContext and ExecutionResult interfaces, but the plugin system loads JavaScript output. The server registry expects CommonJS or ESM exports matching the createServerAdapter() contract.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}