# create-headless-agent

create-headless-agent scaffolds headless TypeScript agents using Bun and @openrouter/agent. Builds CLI utilities, API servers, queue workers, and data pipelines without a terminal UI.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 320 installs · ★ 327 repo stars
- Author: OpenRouterTeam
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/OpenRouterTeam/skills/tree/HEAD/skills/create-headless-agent/SKILL.md
- Updated: 2026-11-06
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/create-headless-agent

## What it does

The skill sets up a headless TypeScript project without readline interfaces or ANSI styling. It relies on `@openrouter/agent` to manage the core loop: model queries, tool calls, and exit conditions. You get a clean programmatic wrapper exposing the agent as a CLI command, a library export, a `Bun.serve()` HTTP server, or an MCP server.

During scaffolding, it asks for the project name and presents an interactive checklist of features. You can toggle OpenRouter server-side tools like web search or datetime, attach local file utilities, and configure architecture modules such as JSONL session persistence or Zod schema validation.

The local shell tool stays locked until you pass `--allow-shell`, and once enabled, it runs outside working directory boundaries. Running the generated agent requires Bun 1.1 or higher alongside a valid `OPENROUTER_API_KEY`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenRouterTeam/skills --skill create-headless-agent -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/create-headless-agent/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/create-headless-agent/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenRouterTeam/skills --skill create-headless-agent -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/create-headless-agent/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenRouterTeam/skills --skill create-headless-agent -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/create-headless-agent/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenRouterTeam/skills skills/create-headless-agent
```

2. **Manually: put the files in place**
- File: `.github/skills/create-headless-agent/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenRouterTeam/skills --skill create-headless-agent -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenRouterTeam/skills --path skills/create-headless-agent
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/create-headless-agent/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenRouterTeam/skills --skill create-headless-agent -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenRouterTeam/skills/tree/HEAD/skills/create-headless-agent/SKILL.md

## When to use it
- scaffold a headless CLI agent in TypeScript running on Bun
- expose an OpenRouter agent pipeline as an HTTP server or MCP tool
- automate batch file tasks with programmatic model calls and JSON output
- build queue workers with retry logic and persistent JSONL sessions

## Example prompts
- Scaffold a headless agent in TypeScript for automated data processing with Bun
- Create a CLI tool using @openrouter/agent with web search and file edit tools
- Set up an MCP server entry point for a headless OpenRouter agent

## Similar
- [npx-cli](https://affpapa.org/en/nevibecode/skills/npx-cli.md) — skill · 309 installs
- [bun-runtime](https://affpapa.org/en/nevibecode/skills/secondsky-bun-runtime.md) — skill · 435 installs
- [pinme-llm](https://affpapa.org/en/nevibecode/skills/pinme-llm.md) — skill · 511 installs
- [vapi-bootstrap-framework](https://affpapa.org/en/nevibecode/skills/vapi-bootstrap-framework.md) — skill · 314 installs
- [headless-caching-strategy](https://affpapa.org/en/nevibecode/skills/headless-caching-strategy.md) — skill · 1100 installs
- [write-script-bun](https://affpapa.org/en/nevibecode/skills/write-script-bun.md) — skill · ★ 18673 repo stars

From the same set: [openrouterteam/skills](https://affpapa.org/en/nevibecode/by/openrouterteam/skills.md) — 16 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
