mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/docs/adapters/overview.md
dotta 11ff24cd22 docs: fix adapter type references and complete adapter table 
- Fix openclaw → openclaw_gateway type key in adapters overview and managing-agents guide
- Add missing adapters to overview table: hermes_local, cursor, pi_local
- Mark gemini_local as experimental (adapter package exists but not in stable type enum)
- Update "Choosing an Adapter" recommendations to match stable adapter set

Co-Authored-By: Paperclip <noreply@paperclip.ing>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-27 01:05:08 -05:00

2.6 KiB
Raw Blame History

title summary
Adapters Overview What adapters are and how they connect agents to Paperclip

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

Adapter Type Key Description
Claude Local claude_local Runs Claude Code CLI locally
Codex Local codex_local Runs OpenAI Codex CLI locally
Gemini Local gemini_local Runs Gemini CLI locally (experimental — adapter package exists, not yet in stable type enum)
OpenCode Local opencode_local Runs OpenCode CLI locally (multi-provider provider/model)
Hermes Local hermes_local Runs Hermes CLI locally
Cursor cursor Runs Cursor in background mode
Pi Local pi_local Runs an embedded Pi agent locally
OpenClaw Gateway openclaw_gateway Connects to an OpenClaw gateway endpoint
Process process Executes arbitrary shell commands
HTTP http Sends 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:

Registry What it does
Server Executes agents, captures results
UI Renders run transcripts, provides config forms
CLI Formats terminal output for live watching

Choosing an Adapter

  • Need a coding agent? Use claude_local, codex_local, opencode_local, or hermes_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