Adapters are the bridge between DarkDuck’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, DarkDuck:
- Looks up the agent’s
adapterType and adapterConfig
- Calls the adapter’s
execute() function with the execution context
- The adapter spawns or calls the agent runtime
- 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) |
| 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 |
| 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 `darkduck run --watch`
| 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 | Recommended Adapter |
|---|
| Coding agent with Claude | claude_local |
| Coding agent with OpenAI | codex_local |
| Multi-provider flexibility | opencode_local |
| Run a script or command | process |
| Call an external service | http |
| Something custom | Create your own |
For most use cases, claude_local or codex_local are the best starting points. They support session persistence, skills injection, and structured output parsing out of the box.
Common Configuration Fields
Most adapters share these configuration fields:
| Field | Description |
|---|
cwd | Working directory for the agent process |
model | LLM model to use |
promptTemplate | Prompt template with {{variable}} substitution |
env | Environment variables (supports secret refs) |
timeoutSec | Maximum execution time |
graceSec | Grace period before force-kill after timeout |
