Headless Adapters
Purpose
Schema-driven adapter for headless CLI agents. No code required - just define a JSON schema describing how to interact with the CLI.
Use Case Tool
Wrap headless CLI agent headless command
Create new schemas Schema Creation Guide
Quick Start
-
Check if a schema exists in schemas/
-
Run the adapter: ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
CLI Commands
headless
Schema-driven adapter for ANY headless CLI agent.
bunx @plaited/agent-eval-harness headless --schema <path>
Options:
Flag Description Required
-s, --schema
Path to adapter schema (JSON) Yes
Schema Format:
{ "version": 1, "name": "my-agent", "command": ["my-agent-cli"], "sessionMode": "stream", "prompt": { "flag": "-p" }, "output": { "flag": "--output-format", "value": "stream-json" }, "autoApprove": ["--allow-all"], "outputEvents": [ { "match": { "path": "$.type", "value": "message" }, "emitAs": "message", "extract": { "content": "$.text" } } ], "result": { "matchPath": "$.type", "matchValue": "result", "contentPath": "$.content" } }
Session Modes:
Mode Description Use When
stream
Keep process alive, multi-turn via stdin CLI supports session resume
iterative
New process per turn, accumulate history CLI is stateless
Pre-built Schemas
Tested schemas are available in schemas/:
Schema Agent Mode Auth Env Var Status
claude-headless.json
Claude Code stream ANTHROPIC_API_KEY
Tested
gemini-headless.json
Gemini CLI iterative GEMINI_API_KEY
Tested
Usage:
Claude Code
ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
Gemini CLI
GEMINI_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/gemini-headless.json
Creating a Schema
-
Explore the CLI's --help to identify prompt, output, and auto-approve flags
-
Capture sample JSON output from the CLI
-
Map JSONPath patterns to output events
-
Create schema file based on an existing template
-
Test with headless command
See Schema Creation Guide for the complete workflow.
Troubleshooting
Common Issues
Issue Likely Cause Solution
Tool calls not captured JSONPath not iterating arrays Use [*] wildcard syntax - see guide
"unexpected argument" error Stdin mode misconfigured Use stdin: true
- see guide
401 Authentication errors API key not properly configured Set the correct API key environment variable (see Pre-built Schemas table)
Timeout on prompt JSONPath not matching Capture raw CLI output, verify paths - see guide
Empty responses Content extraction failing Check extract paths - see guide
Complete troubleshooting documentation: Troubleshooting Guide
External Resources
- AgentSkills Spec: agentskills.io
Related
- agent-eval-harness skill - Running evaluations against adapters