/create-agent-tui

name: create-agent-tui
description: Scaffolds a complete agent TUI in TypeScript using @openrouter/agent — like create-react-app for terminal agents. Generates a customizable terminal interface with three input styles, four tool display modes, ASCII banners, streaming output, session persistence, and configurable tools. Use when building an agent, creating a TUI, scaffolding an agent project, or building a coding assistant.

Create Agent TUI

Scaffolds a complete agent TUI in TypeScript targeting OpenRouter. The generated project uses `@openrouter/agent` for the inner loop (model calls, tool execution, stop conditions) and provides the outer shell: a customizable terminal interface, configuration, session management, tool definitions, and an entry point.

Architecture draws from three production agent systems:

• **pi-mono/coding-agent** — three-layer separation, JSONL sessions, pluggable tool operations
• **Claude Code** — tool metadata (read-only, destructive, approval), system prompt composition
• **Codex CLI** — layered config, approval flow with session caching, structured logging

Prerequisites

• Node.js 18+
• `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 agent from scratch | Present checklist below → follow Generation Workflow | | Add tools to an existing harness | Read [references/tools.md](references/tools.md), present tool checklist only | | Add a harness module | Read [references/modules.md](references/modules.md), generate the module | | Add an API server entry point | Read [references/server-entry-points.md](references/server-entry-points.md) |

---

Interactive Tool Checklist

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

OpenRouter Server Tools (server-side, zero implementation)

| Tool | Type string | Default | Config | |------|------------|---------|--------| | Web Search | `openrouter:web_search` | ON | engine, max_results, domain filtering | | Datetime | `openrouter:datetime` | ON | timezone | | Image Generation | `openrouter:image_generation` | OFF | model, quality, size, format |

Server tools go in the `tools` array alongside user-defined tools. No client code needed — OpenRouter executes them.

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

| Tool | Default | Description | |------|---------|-------------| | File Read | ON | Read files with offset/limit, detect images | | 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 | | JS REPL | OFF | Persistent Node.js environment | | Sub-agent Spawn | OFF | Delegate tasks to child agents | | Plan/Todo | OFF | Track multi-step task progress | | Request User Input | OFF | Structured multiple-choice questions | | Web Fetch | OFF | Fetch and extract text from web pages | | View Image | OFF | Read local images as base64 | | Custom Tool Template | ON | Empty skeleton for domain-specific tools |

Harness Modules (architectural components)

| Module | Default | Description | |--------|---------|-------------| | Session Persistence | ON | JSONL append-only conversation log | | ASCII Logo Banner | OFF | Custom ASCII art banner on startup — ask for project name | | Context Compaction | OFF | Summarize older messages when context is long | | System Prompt Composition | OFF | Assemble instructions from static + dynamic context | | Tool Permissions / Approval | OFF | Gate dangerous tools behind user confirmation | | Structured Event Logging | OFF | Emit events for tool calls, API requests, errors | | `@`-file References | OFF | `@filename` to attach file content to next message | | `!` Shell Shortcut | OFF | `!command` to run shell and inject output into context | | Multi-line Input | OFF | Shift+Enter for multi-line (requires raw terminal mode) |

Slash Commands (user-facing REPL commands)

| Command | Default | Description | |---------|---------|-------------| | `/model` | ON | Switch model via OpenRouter API | | `/new` | ON | Start a fresh conversation | | `/help` | ON | List available commands | | `/compact` | OFF | Manually trigger context compaction | | `/session` | OFF | Show session metadata and token usage | | `/export` | OFF | Save conversation as Markdown |

When slash commands are enabled, generate `src/commands.ts` with a command registry. See [references/slash-commands.md](references/slash-commands.md) for specs.

Visual Customization (present as single-select for each)

**Input style** — how the prompt looks. See [references/input-styles.md](references/input-styles.md):

| Style | Default | Description | |-------|---------|-------------| | `block` | ON | Full-width background box with `›` prompt, adapts to terminal theme | | `bordered` | | Horizontal `─` lines above and below input | | `plain` | | Simple `> ` readline prompt, no escape sequences | | Other | | User describes what they want — implement a custom input style |

**Tool display** — how tool calls appear during execution. See [references/tool-display.md](references/tool-display.md):

| Style | Default | Description | |-------|---------|-------------| | `grouped` | ON | Bold action labels with tree-branch output | | `emoji` | | Per-call `⚡`/`✓` markers with args and timing | | `minimal` | | Aggregated one-liner summaries | | `hidden` | | No tool output | | Other | | User describes what they want — implement a custom display |

**Loader animation** — shown while waiting for model response. See [references/loader.md](references/loader.md):

| Style | Default | Description | |-------|---------|-----