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

> Discover Paperclip Agent Adapters. Explore 11 built-in options like Claude Code and Gemini, and learn to easily configure custom adapters via npm or local directories.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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/main/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`).

```bash

# Register from npm

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

```

```bash

# 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/main/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`](https://github.com/paperclipai/paperclip/blob/main/ui-parser.js) — enables the web UI to render custom transcript formats

*Source: [[`docs/adapters/overview.md`](https://github.com/paperclipai/paperclip/blob/main/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:

```bash

# 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:

```json
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/main/docs/adapters/creating-an-adapter.md)](https://github.com/paperclipai/paperclip/blob/master/docs/adapters/creating-an-adapter.md), the core [`execute.ts`](https://github.com/paperclipai/paperclip/blob/main/execute.ts) skeleton:

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/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/main/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`](https://github.com/paperclipai/paperclip/blob/main/src/index.ts) with `createServerAdapter()` export and [`src/server/execute.ts`](https://github.com/paperclipai/paperclip/blob/main/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/`](https://github.com/paperclipai/paperclip/tree/master/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.