Run your AI SDK agent in the terminal

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.

Copy link to headingOverview

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()

Copy link to headingPrerequisites

Before you begin, make sure you have:

• The ai package and a provider package (e.g., @ai-sdk/openai)
• A ToolLoopAgent to run

Copy link to headingSteps

Copy link to headingInstall the packages

Install ai alongside @ai-sdk/tui and your provider package:

pnpm i ai @ai-sdk/tui @ai-sdk/openai

npm i ai @ai-sdk/tui @ai-sdk/openai

yarn add ai @ai-sdk/tui @ai-sdk/openai

bun add ai @ai-sdk/tui @ai-sdk/openai

Copy link to headingRun 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.

Copy link to headingConfigure 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,
});

Copy link to headingPrompt 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.

Copy link to headingWhen 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.

Copy link to headingKeyboard controls

The terminal UI responds to these keys:

Copy link to headingNext steps

• See Building agents for creating ToolLoopAgent instances.
• Read Tool approvals to configure human review of tool calls.
• Check the runAgentTUI reference for every parameter.