---

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

1. Check if a schema exists in schemas/
2. Run the adapter:

   CopyANTHROPIC_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.

Copybunx @plaited/agent-eval-harness headless --schema <path>

Options:

Schema Format:

Copy{
  "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:

Pre-built Schemas

Tested schemas are available in schemas/:

Usage:

Copy# 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

Complete troubleshooting documentation: Troubleshooting Guide

External Resources

• AgentSkills Spec: agentskills.io

Related

• agent-eval-harness skill - Running evaluations against adapters