# Create Agent Adapter

Adds support for a new CLI, API or custom agent across server, UI and CLI.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill create-agent-adapter -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill create-agent-adapter -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill create-agent-adapter -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill create-agent-adapter -g -a gemini-cli -y`

## Description

Create or modify Paperclip agent adapters across server, UI, and CLI surfaces. Use when adding support for a new CLI agent, API agent, custom process, or adapter package.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Creating a Paperclip Agent Adapter

An adapter bridges Paperclip's orchestration layer to a specific AI agent runtime (Claude Code, Codex CLI, a custom process, an HTTP endpoint, etc.). Each adapter is a self-contained package that provides implementations for **three consumers**: the server, the UI, and the CLI.

---

## 1. Architecture Overview

```
packages/adapters/<name>/
  src/
    index.ts            # Shared metadata (type, label, models, agentConfigurationDoc)
    server/
      index.ts          # Server exports: execute, sessionCodec, parse helpers
      execute.ts        # Core execution logic (AdapterExecutionContext -> AdapterExecutionResult)
      parse.ts          # Stdout/result parsing for the agent's output format
    ui/
      index.ts          # UI exports: parseStdoutLine, buildConfig
      parse-stdout.ts   # Line-by-line stdout -> TranscriptEntry[] for the run viewer
      build-config.ts   # CreateConfigValues -> adapterConfig JSON for agent creation form
    cli/
      index.ts          # CLI exports: formatStdoutEvent
      format-event.ts   # Colored terminal output for `paperclipai run --watch`
  package.json
  tsconfig.json
```

Three separate registries consume adapter modules:

| Registry | Location | Interface |
|----------|----------|-----------|
| Server | `server/src/adapters/registry.ts` | `ServerAdapterModule` |
| UI | `ui/src/adapters/registry.ts` | `UIAdapterModule` |
| CLI | `cli/src/adapters/registry.ts` | `CLIAdapterModule` |

---

## 2. Shared Types (`@paperclipai/adapter-utils`)

All adapter interfaces live in `packages/adapter-utils/src/types.ts`. Import from `@paperclipai/adapter-utils` (types) or `@paperclipai/adapter-utils/server-utils` (runtime helpers).

### Core Interfaces

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/.agents/skills/create-agent-adapter/SKILL.md