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