headless-adapters

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

1. Check if a schema exists in schemas/
2. 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

1. Explore the CLI's --help to identify prompt, output, and auto-approve flags
2. Capture sample JSON output from the CLI
3. Map JSONPath patterns to output events
4. Create schema file based on an existing template
5. 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