youdotcom-oss 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
--helpto 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
headlesscommand
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