# Run your AI SDK agent in the terminal **Author:** Ben Sabic --- The `@ai-sdk/tui` package runs a `ToolLoopAgent` in an interactive terminal, so you can chat with your agent locally without building a UI. The terminal interface handles prompt input, streamed responses, markdown rendering, tool cards, reasoning sections, scrolling, and tool approval prompts. It's a good fit for local development, demos, and internal tools where a terminal experience is enough. You build the agent as usual and hand it to `runAgentTUI`. ## Overview In this guide, you'll learn how to: - Install `@ai-sdk/tui` and run a `ToolLoopAgent` with `runAgentTUI` - Configure how tool calls, reasoning, and statistics are displayed - Prompt for tool approval before the agent runs a tool - Know when to use the terminal UI versus `agent.generate()` or `agent.stream()` ## Prerequisites Before you begin, make sure you have: - The `ai` package and a provider package (e.g., `@ai-sdk/openai`) - A `ToolLoopAgent` to run ## Steps ### Install the packages Install `ai` alongside `@ai-sdk/tui` and your provider package: ### Run the agent Create a `ToolLoopAgent` and pass it to `runAgentTUI`. This opens an interactive session that runs until you exit. `import { openai } from '@ai-sdk/openai'; import { runAgentTUI } from '@ai-sdk/tui'; import { ToolLoopAgent, tool } from 'ai'; import { z } from 'zod'; const agent = new ToolLoopAgent({ model: openai('gpt-5'), instructions: 'You are a helpful terminal assistant. Answer in markdown and use tools when they help.', tools: { weather: tool({ description: 'Get the weather in a location', inputSchema: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: 72, }), }), }, }); await runAgentTUI({ title: 'Weather Agent', agent, });` Run the file with a TypeScript runner such as `tsx agent.ts`. The session stays open until you exit with `Esc` or `Ctrl+C`. ### Configure the display Pass display options to `runAgentTUI` to control how tool calls, reasoning, and response statistics appear. `await runAgentTUI({ title: 'Weather Agent', agent, tools: 'auto-collapsed', reasoning: 'collapsed', responseStatistics: 'outputTokensPerSecond', contextSize: 200_000, });` | Option | Values | Default | Description | | -------------------- | ------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` | `'full'`, `'collapsed'`, `'auto-collapsed'`, `'hidden'` | `'auto-collapsed'` | How tool calls render. `'full'` shows input and output, `'collapsed'` shows only tool cards, `'auto-collapsed'` keeps the latest tool expanded until another section appears, and `'hidden'` omits tool calls | | `reasoning` | `'full'`, `'collapsed'`, `'auto-collapsed'`, `'hidden'` | `'auto-collapsed'` | How reasoning renders, with the same options as `tools` | | `responseStatistics` | `'outputTokensPerSecond'`, `'outputTokenCount'` | `'outputTokensPerSecond'` | Whether to show output token throughput or total output token count | | `contextSize` | `number` | — | When set, shows total token usage as a percentage of the model's context window | ### Prompt for tool approval `runAgentTUI` supports the `ToolLoopAgent` tool approval flow. When the agent requests manual approval for a tool, the terminal prompts you to approve or deny it before the agent continues. Configure approvals with `toolApproval` on the agent: `const agent = new ToolLoopAgent({ model: openai('gpt-5'), tools: { weather }, toolApproval: { weather: ({ location }) => location.toLowerCase().includes('san francisco') ? 'approved' : 'user-approval', }, }); await runAgentTUI({ title: 'Weather Agent', agent });` When a tool needs review, press `y` to approve or `n` to deny. In this example, weather requests for San Francisco run automatically, while requests for every other location wait for your approval. ### When to use the terminal UI `runAgentTUI` is built for agents that run directly from free-form terminal input. The agent must not require per-call options and must not use structured output, because the terminal UI can't infer those values from a typed prompt. For fixed prompts, call options, structured output, custom result inspection, or custom stream processing, call `agent.generate()` or `agent.stream()` directly instead. ### Keyboard controls The terminal UI responds to these keys: | Key | Action | | --------------------- | ------------------------------------ | | `Enter` | Submit the prompt | | `y` / `n` | Approve or deny a tool call | | `Up` / `Down` | Scroll the transcript | | `PageUp` / `PageDown` | Scroll the transcript by a full page | | `Ctrl+L` | Repaint the screen | | `Esc` / `Ctrl+C` | Exit | ### Next steps - See [Building agents](https://ai-sdk.dev/docs/agents/building-agents) for creating `ToolLoopAgent` instances. - Read [Tool approvals](https://ai-sdk.dev/v7/docs/agents/tool-approvals) to configure human review of tool calls. - Check the [`runAgentTUI`](https://ai-sdk.dev/v7/docs/reference/ai-sdk-tui/run-agent-tui) [reference](https://ai-sdk.dev/v7/docs/reference/ai-sdk-tui/run-agent-tui) for every parameter. --- [View full KB sitemap](/kb/sitemap.md)