| name | headless-adapters |
| description | Discover, create, and validate headless adapters for agent integration. Includes scaffolding tools and schema-driven compliance testing. |
| compatibility | Bun >= 1.2.9 |
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.
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"
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:
ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
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
Related
