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.

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

Before you begin, make sure you have:

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

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

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

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.

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,
});

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.

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.

The terminal UI responds to these keys:

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