create-agent-adapter

Topics in the source

• Creating a Paperclip Agent Adapter
• 1. Architecture Overview
• 2. Shared Types (@paperclipai/adapter-utils)
• Core Interfaces
• Module Interfaces
• 2.1 Adapter Environment Test Contract
• 3. Step-by-Step: Creating a New Adapter
• 3.1 Create the Package

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. -- 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 | -- 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). -- Every server adapter must implement testEnvironment(...). This powers the board UI "Test environment" button in agent configuration. Guidelines: Return structured diagnostics, never throw for expected findings. Use error for invalid/unusable runtime setup (bad cwd, missing command, invalid URL). Use warn for non-blocking but important situations. Use info for successful checks and context. Severity policy is product-critical: warnin

This is an excerpt. Refer to the complete source and its current requirements.