Skip to main content
Adapters are the bridge between Paperclip’s orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.

​
How Adapters Work

When a heartbeat fires, Paperclip:
  1. Looks up the agent’s adapterType and adapterConfig
  2. Calls the adapter’s execute() function with the execution context
  3. The adapter spawns or calls the agent runtime
  4. The adapter captures stdout, parses usage/cost data, and returns a structured result

​
Built-in Adapters

AdapterType KeyDescription
Claude Localclaude_localRuns Claude Code CLI locally
Codex Localcodex_localRuns OpenAI Codex CLI locally
ProcessprocessExecutes arbitrary shell commands
HTTPhttpSends webhooks to external agents

​
Adapter Architecture

Each adapter is a package with three modules: 
packages/adapters/<name>/
  src/
    index.ts            # Shared metadata (type, label, models)
    server/
      execute.ts        # Core execution logic
      parse.ts          # Output parsing
      test.ts           # Environment diagnostics
    ui/
      parse-stdout.ts   # Stdout -> transcript entries for run viewer
      build-config.ts   # Form values -> adapterConfig JSON
    cli/
      format-event.ts   # Terminal output for `paperclipai run --watch`
Three registries consume these modules:
RegistryWhat it does
ServerExecutes agents, captures results
UIRenders run transcripts, provides config forms
CLIFormats terminal output for live watching

​
Choosing an Adapter

  • Need a coding agent? Use claude_local or codex_local
  • Need to run a script or command? Use process
  • Need to call an external service? Use http
  • Need something custom? Create your own adapter