Adapter Reference

Adapters define how the runtime interacts with external tools and agents. Amurg ships with eight adapter profiles, each tailored to a different execution model. Three generic profiles handle arbitrary CLIs, batch jobs, and HTTP APIs. Four first-class profiles provide native integration with Claude Code, GitHub Copilot, OpenAI Codex, and Kilo Code. The external profile offers a JSON-Lines stdio protocol for custom adapters.

Generic CLI

Profile: generic-cli — Execution model: Interactive — Config key: cli

Spawns an interactive CLI process. User input is written to stdin, and stdout/stderr are streamed back as output. The process lifetime is controlled by spawn_policy: either a new process per session or a single persistent process.

Field Type Default Description
commandstringrequiredPath to the CLI executable
args[]string[]Command-line arguments
work_dirstring""Working directory for the process
envmap[string]string{}Additional environment variables
spawn_policystring"per-session""per-session" or "persistent"
 
{
  "id": "my-agent",
  "name": "My CLI Agent",
  "profile": "generic-cli",
  "cli": {
    "command": "/usr/local/bin/my-agent",
    "args": ["--interactive", "--no-color"],
    "work_dir": "/home/user/projects",
    "env": { "AGENT_MODE": "chat" },
    "spawn_policy": "per-session"
  }
}

Generic Job

Profile: generic-job — Execution model: Run-to-completion — Config key: job

Spawns a process that runs to completion on each user message. The user input is passed as stdin, and all stdout/stderr output is collected until the process exits. A max_runtime limit prevents runaway processes.

Field Type Default Description
commandstringrequiredPath to the executable
args[]string[]Command-line arguments
work_dirstring""Working directory for the process
envmap[string]string{}Additional environment variables
max_runtimeduration"5m"Maximum execution time before the process is killed
 
{
  "id": "batch-runner",
  "name": "Batch Runner",
  "profile": "generic-job",
  "job": {
    "command": "/usr/local/bin/batch-job",
    "args": ["--output-json"],
    "work_dir": "/tmp/jobs",
    "env": {},
    "max_runtime": "5m"
  }
}

Generic HTTP

Profile: generic-http — Execution model: Request-response — Config key: http

Sends each user message as an HTTP request to a remote endpoint and returns the response body as output. Useful for integrating with LLM APIs, webhooks, or any HTTP service.

Field Type Default Description
base_urlstringrequiredTarget URL for requests
methodstring"POST"HTTP method
headersmap[string]string{}Additional HTTP headers
timeoutduration"60s"Request timeout
 
{
  "id": "llm-proxy",
  "name": "LLM Proxy",
  "profile": "generic-http",
  "http": {
    "base_url": "https://api.example.com/v1/chat",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer sk-...",
      "Content-Type": "application/json"
    },
    "timeout": "60s"
  }
}

External

Profile: external — Execution model: Interactive — Config key: external

Spawns a long-lived adapter process that communicates via JSON-Lines over stdin/stdout. The runtime multiplexes multiple sessions over a single process using session_id fields. This is the most flexible adapter profile, suitable for building custom integrations in any language.

Field Type Default Description
commandstringrequiredPath to the adapter executable
args[]string[]Command-line arguments
work_dirstring""Working directory for the adapter process
envmap[string]string{}Additional environment variables

JSON-Lines Protocol: Runtime to Adapter

Type Fields Description
session.startsession_idInitialize a new session
user.inputsession_id, contentDeliver user message to the adapter
file.inputsession_id, file_name, file_mime_type, file_pathDeliver a file to the adapter (path on disk)
permission.responsesession_id, request_id, approvedRespond to a permission request from the adapter
stopsession_idRequest the adapter stop processing
session.closesession_idClose the session and release resources

JSON-Lines Protocol: Adapter to Runtime

Type Fields Description
outputsession_id, content, channelAgent output (channel defaults to "stdout")
turn.completesession_idSignal the agent has finished its turn
file.outputsession_id, file_name, file_mime_type, file_pathProduce a file for the user (path on disk)
permission.requestsession_id, request_id, tool, description, resourceRequest permission for a tool action

Example Exchange

// Runtime -> Adapter: start session
{"type":"session.start","session_id":"abc-123"}

// Runtime -> Adapter: user message
{"type":"user.input","session_id":"abc-123","content":"Hello, agent!"}

// Adapter -> Runtime: agent output
{"type":"output","session_id":"abc-123","content":"Hello! How can I help?","channel":"stdout"}

// Adapter -> Runtime: signal turn complete
{"type":"turn.complete","session_id":"abc-123"}

// Runtime -> Adapter: file delivery
{"type":"file.input","session_id":"abc-123","file_name":"data.csv","file_mime_type":"text/csv","file_path":"/tmp/files/data.csv"}

// Adapter -> Runtime: file output
{"type":"file.output","session_id":"abc-123","file_name":"result.png","file_mime_type":"image/png","file_path":"/tmp/output/result.png"}

// Runtime -> Adapter: stop session
{"type":"stop","session_id":"abc-123"}

// Runtime -> Adapter: close session
{"type":"session.close","session_id":"abc-123"}
{
  "id": "custom-agent",
  "name": "Custom Agent",
  "profile": "external",
  "external": {
    "command": "/usr/local/bin/my-adapter",
    "args": ["--mode", "jsonl"],
    "work_dir": "/opt/agents",
    "env": { "LOG_LEVEL": "debug" }
  }
}

Claude Code

Profile: claude-code — Execution model: Interactive — Config key: claude_code

First-class integration with Anthropic's Claude Code CLI. Spawns a new claude process per Send() call, using --resume with native session IDs for conversation continuity. Supports model selection, permission modes, tool allowlists, max turns, and system prompts.

Field Type Default Description
commandstring"claude"Path to the Claude Code CLI
work_dirstring""Working directory
envmap[string]string{}Additional environment variables
modelstring""Model name, e.g. "sonnet"
permission_modestring""e.g. "dangerously-skip-permissions"
max_turnsint0Max agentic turns per invocation
allowed_tools[]string[]Allowlisted tools, e.g. "Read", "Write", "Bash"
system_promptstring""Custom system prompt
 
{
  "id": "claude",
  "name": "Claude Code",
  "profile": "claude-code",
  "claude_code": {
    "command": "claude",
    "work_dir": "/home/user/projects",
    "env": {},
    "model": "sonnet",
    "permission_mode": "dangerously-skip-permissions",
    "max_turns": 50,
    "allowed_tools": ["Read", "Write", "Bash"],
    "system_prompt": "You are a helpful coding assistant."
  }
}

GitHub Copilot

Profile: github-copilot — Execution model: Interactive — Config key: copilot

First-class integration with the GitHub Copilot CLI. Invokes copilot -p --silent --no-color for non-interactive operation. Uses --continue for session continuity across turns, --model for model selection, and --allow-all / --allow-tool / --deny-tool for permission control.

Field Type Default Description
commandstring"copilot"Path to the Copilot CLI
work_dirstring""Working directory
envmap[string]string{}Additional environment variables
modelstring""Model name, e.g. "claude-sonnet-4.5"
allowed_tools[]string[]Tools to allow via --allow-tool flags
denied_tools[]string[]Tools to deny via --deny-tool flags
 
{
  "id": "copilot",
  "name": "GitHub Copilot",
  "profile": "github-copilot",
  "copilot": {
    "command": "copilot",
    "work_dir": "/home/user/projects",
    "env": {},
    "model": "claude-sonnet-4.5",
    "allowed_tools": ["fs_read", "fs_write"],
    "denied_tools": ["shell_execute"]
  }
}

Codex

Profile: codex — Execution model: Run-to-completion — Config key: codex

First-class integration with OpenAI's Codex CLI. Invokes codex exec --json --color never with full JSONL streaming of events (turn.started, item.completed, etc.). Uses exec resume --last for session continuity. Permission control via --ask-for-approval and --sandbox flags. Working directory override via --cd and model selection via --model.

Field Type Default Description
commandstring"codex"Path to the Codex CLI
work_dirstring""Working directory (passed as --cd)
envmap[string]string{}Additional environment variables
modelstring""Model name, e.g. "gpt-5"
approval_modestring""Approval policy: "untrusted", "on-request", or "never"
sandbox_modestring""Sandbox policy: "read-only", "workspace-write", or "danger-full-access"
 
{
  "id": "codex",
  "name": "OpenAI Codex",
  "profile": "codex",
  "codex": {
    "command": "codex",
    "work_dir": "/home/user/projects",
    "env": {},
    "model": "gpt-5",
    "approval_mode": "on-request",
    "sandbox_mode": "workspace-write"
  }
}

Kilo Code

Profile: kilo-code — Execution model: Interactive — Config key: kilo

First-class integration with the Kilo Code CLI. Invokes kilo run --auto --json for non-interactive JSON output. Uses --continue for session continuity across turns and --yolo to skip permission prompts. Model and provider selection are configured via the model and provider fields, or through the KILO_MODEL and KILO_PROVIDER environment variables.

Field Type Default Description
commandstring"kilo"Path to the Kilo Code CLI
work_dirstring""Working directory
envmap[string]string{}Additional environment variables
modelstring""Model name, e.g. "anthropic/claude-sonnet-4"
providerstring""Provider name, e.g. "anthropic", "openrouter"
 
{
  "id": "kilo",
  "name": "Kilo Code",
  "profile": "kilo-code",
  "kilo": {
    "command": "kilo",
    "work_dir": "/home/user/projects",
    "env": {
      "KILO_MODEL": "anthropic/claude-sonnet-4",
      "KILO_PROVIDER": "anthropic"
    },
    "model": "anthropic/claude-sonnet-4",
    "provider": "anthropic"
  }
}

Adapter Capabilities

The following table shows the capabilities declared by each profile. These values match pkg/protocol/profiles.go and are sent to the hub during runtime registration.

Profile NativeSessionIDs TurnCompletion ResumeAttach ExecModel
generic-cli No No No Interactive
generic-job No Yes No Run-to-completion
generic-http No Yes No Request-response
claude-code Yes Yes Yes Interactive
github-copilot No Yes Yes Interactive
codex No Yes Yes Run-to-completion
kilo-code No Yes Yes Interactive
external No Yes No Interactive

Capability Definitions

NativeSessionIDs — The adapter manages its own session identifiers internally. The runtime stores and reuses them for session continuity. Only Claude Code uses native session IDs.

TurnCompletion — The adapter signals when it has finished processing a user message (turn). This enables the hub to enforce turn-based gating, preventing the user from sending another message until the agent is done.

ResumeAttach — The adapter can resume a previous session's conversation context. Claude Code uses --resume, Copilot uses --continue, Codex uses exec resume --last, and Kilo Code uses --continue.