/create-headless-agent

name: create-headless-agent
description: Scaffolds a headless agent in TypeScript using @openrouter/agent and Bun — for CLI tools, API servers, queue workers, and pipelines. No terminal UI. Use when building a headless agent, programmatic agent, CLI tool that uses AI, batch agent, pipeline agent, API agent, agent without a UI, or agent service.

Create Headless Agent

Scaffolds a headless agent in TypeScript targeting OpenRouter. The generated project uses `@openrouter/agent` for the inner loop (model calls, tool execution, stop conditions) and provides a clean programmatic shell: configuration, session management, tool definitions, and one or more entry points (CLI, HTTP server, MCP server, or library import). No terminal UI, no readline, no ANSI — just input in, result out.

Prerequisites

• Bun 1.1+
• `OPENROUTER_API_KEY` from [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys)
• For full SDK reference, see the `openrouter-typescript-sdk` skill

---

Decision Tree

| User wants to... | Action | |---|---| | Build a new headless agent | Present checklist below, follow Generation Workflow | | Add tools to an existing agent | Read [references/tools.md](references/tools.md), present tool checklist only | | Add a module | Read [references/modules.md](references/modules.md), generate the module | | Add an entry point | Read [references/entry-points.md](references/entry-points.md), generate it |

---

Interactive Feature Checklist

Present this as a multi-select checklist. Items marked **ON** are pre-selected defaults.

Entry Points (pick one or more)

| Entry Point | Default | Description | |-------------|---------|-------------| | CLI | ON | args/stdin to agent to stdout, `--json` for NDJSON | | Library module | ON | `import { runAgent } from './agent'` | | HTTP server | OFF | `Bun.serve()` with SSE streaming | | MCP server | OFF | Expose as MCP tool via stdio |

OpenRouter Server Tools (server-side, zero implementation)

| Tool | Type string | Default | |------|------------|---------| | Web Search | `openrouter:web_search` | ON | | Web Fetch | `openrouter:web_fetch` | ON | | Datetime | `openrouter:datetime` | ON | | Image Generation | `openrouter:image_generation` | OFF |

Server tools go in the `tools` array alongside user-defined tools. No client code needed — OpenRouter executes them. Docs: [openrouter.ai/docs/guides/features/server-tools](https://openrouter.ai/docs/guides/features/server-tools/overview).

User-Defined Tools (client-side, generated into src/tools/)

| Tool | Default | Description | |------|---------|-------------| | File Read | ON | Read files with offset/limit | | File Write | ON | Write/create files, auto-create directories | | File Edit | ON | Search-and-replace with diff validation | | Glob/Find | ON | File discovery by glob pattern | | Grep/Search | ON | Content search by regex | | Directory List | ON | List directory contents | | Shell/Bash | ON | Execute commands with timeout and output capture | | Custom Tool Template | ON | Empty skeleton for domain-specific tools | | JS/TS REPL | OFF | Persistent Bun REPL | | Sub-agent Spawn | OFF | Delegate tasks to child agents | | View Image | OFF | Read local images as base64 |

Agent Modules (architectural components)

| Module | Default | Description | |--------|---------|-------------| | Session Persistence | ON | JSONL conversation log, `--no-session` to disable | | Retry with Backoff | ON | Built into agent.ts | | Context Compaction | OFF | Summarize when context is long | | Tool Result Offload | OFF | Persist oversized tool outputs to disk, keep preview in context | | System Prompt Composition | OFF | Dynamic instructions from context files | | Tool Approval Flow | OFF | Programmatic approve/reject | | Structured Event Logging | OFF | JSON events to stderr | | Output Schema Validation | OFF | Zod schema constraining response | | Webhook Notifications | OFF | POST on completion |

CLI Output Mode (single-select, if CLI entry point is ON)

| Mode | Default | Description | |------|---------|-------------| | Text | ON | Final response text to stdout | | JSON | OFF | NDJSON event stream | | Quiet | OFF | Exit code only |

---

Generation Workflow

Before generating, **ask the user what to name their agent**. This name is used as:

• the `"name"` field in `package.json`
• the `"bin"` command (so `bun link` makes it a globally-invokable CLI)
• the project directory name (if creating a new directory)

Suggested question: *"What would you like to call your agent? (short kebab-case, e.g. `research-bot` or `docs-helper`)"*. Validate the answer is a valid npm package name (lowercase, kebab-case, no spaces). Default to `my-agent` if the user has no preference. Use the chosen name everywhere the workflow below shows `<agent-name>`.

After getting the name and checklist selections, follow this workflow:

- [ ] Generate package.json with name=<agent-name> and bin={"<agent-name>": "src/cli.ts"}
- [ ] Generate tsconfig.json (Bun-native)
- [ ] Generate src/config.ts
- [ ] Generate src/tools/index.ts wiring selected tools
- [ ] Generate selected tool files in src/tools/ (specs in references/tools.md)
- [ ] Generate src/agent.ts (core runner)
- [ ] If Session Persistence ON: generate src/session.ts (spec in references/modules.md)
- [ ] Generate selected modules (specs in references/modules.md)
- [ ] Generate src/cli.ts entry point with shebang `#!/usr/bin/env bun` (spec in references/entry-points.md)
- [ ] If HTTP server selected: generate src/server.ts (spec in references/entry-points.md)
- [ ] If MCP server selected: generate src/mcp-server.ts (spec in references/entry-points.md)
- [ ] Generate .env.example
- [ ] Generate test/agent.test.ts
- [ ] Run `bun install` to fetch dependencies
- [ ] Verify: run `bunx tsc --noEmit`
- [ ] Run `bun link` inside the project to register <agent-name> globally
- [ ] Verify the command is on PATH: `command -v <agent-name>` should print a path