create-agent-tui: Scaffold a Full Coding Agent in One Command

Most developers building AI agents start the same way: copy some boilerplate, wire up an API client, write a tool execution loop, handle streaming, bolt on a CLI interface. It’s the same plumbing every time, and it’s tedious.

OpenRouter’s create-agent-tui skill skips all of that. One command, and you have a complete TypeScript agent with a terminal UI, file tools, shell execution, streaming, cost tracking, and session persistence. Ready to run with npm start.

What It Is

create-agent-tui is a skill you install via the GitHub CLI. It works with Claude Code, Cursor, Codex, OpenCode, Gemini CLI, Windsurf — basically any AI coding agent that supports gh skill install:

gh skill install OpenRouterTeam/skills create-agent-tui

Once installed, tell your coding agent something like “build me an agent TUI” and it scaffolds the entire project. Think create-react-app, but for terminal agents.

What You Get

The generated project is a real agent harness, not a toy starter. Out of the box you get:

Tools — file read/write/edit, glob, grep, directory listing, shell execution, and a custom tool template for your domain-specific stuff. There are also server-side tools (web search, datetime, image generation) that execute on OpenRouter with zero client code.

The agent loop — multi-turn tool execution, streaming responses, stop conditions (step count, cost limit, specific tool call, or custom functions), and cost tracking with token counts. All of this comes from the @openrouter/agent SDK, so the generated code doesn’t reimplement any of it.

Session persistence — JSONL append-only conversation logs so you can pick up where you left off.

A configurable terminal UI — and this is where it gets interesting.

The UI Is Surprisingly Customizable

Most scaffolding tools give you one look and you’re stuck with it. create-agent-tui gives you options at every layer:

Input styles: Block (full-width colored input box that adapts to your terminal theme via OSC 11 detection), bordered (horizontal line frame), plain (simple readline prompt), or describe your own custom style.

Tool display: Grouped (bold labels with tree-branch output), emoji (per-call markers with timing), minimal (one-liner summaries), hidden, or custom.

Loader animations: Gradient shimmer, braille spinner, trailing dots, or custom.

ASCII banners: Block-letter art sized for 60-column terminals, generated from your project name.

All of these are configurable via the config file or CLI flags at launch:

npm start -- --banner "Acme Bot" --model anthropic/claude-sonnet-4 --input bordered --tool-display emoji

The SDK Does the Hard Part

The generated TUI is a shell around @openrouter/agent, which handles everything that’s actually difficult about building an agent:

• Model calls — client.callModel() works with any model on OpenRouter. Switch models with a flag.
• Tool execution — define tools with tool() and Zod schemas. The SDK validates input and calls your execute function.
• Multi-turn loops — the SDK loops (call model → execute tools → call model) until a stop condition fires.
• Streaming — result.getTextStream() for text, result.getToolCallsStream() for tool calls.
• Shared context — type-safe state shared across tools via sharedContextSchema.
• Turn lifecycle — onTurnStart / onTurnEnd callbacks for logging, compaction triggers, whatever you need.

Your code handles what’s specific to your agent: tool definitions, configuration, the entry point, and the UI. The SDK handles the loop.

Optional Modules

Beyond the defaults, the skill offers harness modules you can opt into during scaffolding:

• Context compaction — summarize older messages when context gets long
• System prompt composition — build instructions from static and dynamic context files
• Tool permissions — gate dangerous tools behind user approval
• Structured event logging — emit events for tool calls, API requests, errors
• Sub-agent spawning — delegate tasks to child agents
• Multi-line input, @-file references, ! shell shortcuts — quality-of-life features for power users

Why This Matters

The barrier to building a custom agent has been “write a lot of boilerplate that has nothing to do with your actual use case.” create-agent-tui removes that barrier entirely. You get a production-quality starting point, and because it’s built on @openrouter/agent, you’re not locked into any specific model — swap between Claude, GPT, Gemini, Llama, or anything else on OpenRouter with a single flag.

If you need a custom agent that talks to your APIs, enforces your cost limits, and looks the way you want it to — this is the fastest way to get there. Install the skill, describe what you want, and start building the parts that actually matter.

How Does create-agent-tui Compare to Claude Code, Cursor, and Codex CLI?

This is the most common question, and the answer is simple: they solve different problems.

	Claude Code	Cursor	Codex CLI	create-agent-tui
What it is	Finished agent product	IDE with AI built in	OpenAI’s terminal agent	Scaffolding tool for building agents
Model lock-in	Claude only	Multi-model	OpenAI only	Any model on OpenRouter
Custom tools	Limited	Extensions	Sandboxed	Fully custom, you own the code
Custom UI	No	No	No	4 input styles, 3+ tool displays, banners
Cost controls	Per-session limits	Subscription	Token limits	Programmable stop conditions (cost, steps, custom)
Own the code	No	No	Partially	Yes — it’s your generated project
Use case	Use an agent	Code in an IDE	Use an agent	Build an agent

Claude Code, Cursor, and Codex CLI are tools you use. They’re excellent at what they do. But you can’t fundamentally change how they work, add domain-specific tools, or ship them as your own product.

create-agent-tui generates a tool you own. The output is a TypeScript project in your repo. Add tools that hit your internal APIs. Wire in approval flows for production deployments. Set cost limits per session. Swap the model per task. Ship it to your team or your customers.

The right analogy: Claude Code is Gmail. create-agent-tui is a mail server framework. Most people want Gmail. Some people need to build their own mail system.

Frequently Asked Questions

What is create-agent-tui and who is it for?

create-agent-tui is an open-source skill from OpenRouter that scaffolds a complete TypeScript AI agent with a terminal interface in one command. It’s for developers who need to build custom agents — with their own tools, UI, and business logic — rather than using an off-the-shelf agent like Claude Code or Cursor.

Can I use create-agent-tui with local models?

Yes. Any model available through OpenRouter works, including self-hosted models you’ve added to your OpenRouter account. You can also modify the generated code to call any OpenAI-compatible API endpoint directly.

How much does it cost to use?

The skill itself is free and open source. You pay for model usage through OpenRouter at their standard per-token pricing. The generated agent includes built-in cost tracking and configurable cost limits so you don’t get surprised.

Is this production-ready or just a demo?

The generated project is a real agent harness with session persistence, structured logging, error handling, and permission gates. It’s designed as a starting point for production agents, not a tutorial. That said, you’ll want to add your own tools and configuration for your specific use case.

What’s the difference between create-agent-tui and create-headless-agent?

create-agent-tui generates an agent with a terminal UI (for interactive use). create-headless-agent generates one without a UI (for scripts, pipelines, API servers, or embedding in other applications). Both use the same @openrouter/agent SDK under the hood.