Create Agent Adapter

This walks you through building a new agent adapter for Paperclip, the system that lets you plug in different AI coding tools like Claude Code or Codex. You get the full architecture: a three-part package structure (server execution, UI parsing, CLI formatting), the exact interfaces to implement, and how to wire everything into the registries. The environment test contract is well documented, which matters because those diagnostics show up in the board UI when users configure agents. If you're adding support for a new CLI tool or API-based agent, this covers the session management, stdout parsing, and config building you need. The concrete examples from claude-local and codex-local adapters make it practical rather than abstract.

skills.sh installs: 329
GitHub stars: 112.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add paperclipai/paperclip --skill create-agent-adapter --agent claude-code

Installs into .claude/skills of the current project.

Files

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

SKILL.md on GitHub