@agentick/tui

Terminal UI for Agentick agents. Uses Ink (React for CLIs) with @agentick/react hooks — same hooks, same streaming, different renderer.

Installation

pnpm add @agentick/tui

Quick Start

Local Agent

import { createApp, Model, Timeline, Section } from "@agentick/core";
import { openai } from "@agentick/openai";
import { createTUI } from "@agentick/tui";

function MyAgent() {
  return (
    <>
      <Model model={openai({ model: "gpt-4o-mini" })} />
      <Section id="system" audience="model">
        You are a helpful assistant.
      </Section>
      <Timeline />
    </>
  );
}

const app = createApp(MyAgent);
createTUI({ app }).start();

Remote Agent

Connect to an Agentick gateway over HTTP/SSE:

import { createTUI } from "@agentick/tui";

createTUI({ url: "https://my-agent.fly.dev/api" }).start();

Custom UI

Replace the default chat interface with your own Ink component:

import { createTUI } from "@agentick/tui";
import { MyDashboard } from "./dashboard.js";

createTUI({ app, ui: MyDashboard }).start();

Alternate Screen

Use the terminal's alternate screen buffer to avoid polluting scrollback:

createTUI({ app, alternateScreen: true }).start();

When enabled, the TUI takes over the alternate screen on start and restores the normal screen on exit. This prevents terminal scrollbar confusion where native scrollback doesn't interact with Ink's rendering.

CLI

The agentick-tui binary launches a TUI from the command line.

# Local app (file exporting an App instance)
agentick-tui --app ./my-app.ts

# Remote gateway
agentick-tui --url https://my-agent.fly.dev/api

# With session ID
agentick-tui --url https://my-agent.fly.dev/api --session my-session

# Custom terminal UI
agentick-tui --app ./my-app.ts --ui ./dashboard.tsx
agentick-tui --app ./my-app.ts --ui ./dashboard.tsx --ui-export MonitorDashboard

Dev (from repo root):

pnpm tui -- --url http://localhost:3000/api --session default

CLI Options

| Flag | Description | | -------------------- | -------------------------------------------------------- | | --app <path> | Path to a file exporting an App instance | | --export <name> | Named export to use (default: auto-detect) | | --url <url> | Remote gateway URL (include the mount path, e.g. /api) | | --session <id> | Session ID (default: "main") | | --ui <name\|path> | Built-in UI name or path to custom UI file | | --ui-export <name> | Named export from custom UI file |

Built-in UIs

| Name | Description | | ------ | ------------------------------------------ | | chat | Default conversational interface (default) |

API

createTUI(options)

Returns { start(): Promise<void> }.

Local options:

| Option | Type | Description | | ----------------- | -------------- | -------------------------------------------- | | app | App | Agentick App instance | | sessionId | string | Session ID (default: "main") | | ui | TUIComponent | Custom UI component (default: Chat) | | alternateScreen | boolean | Use alternate screen buffer (default: false) |

Remote options:

| Option | Type | Description | | ----------------- | -------------- | -------------------------------------------- | | url | string | Gateway URL | | token | string | Auth token | | sessionId | string | Session ID (default: "main") | | ui | TUIComponent | Custom UI component (default: Chat) | | alternateScreen | boolean | Use alternate screen buffer (default: false) |

TUIComponent

Any React component that accepts { sessionId: string }:

import type { TUIComponent } from "@agentick/tui";

const MyUI: TUIComponent = ({ sessionId }) => {
  const { messages, status } = useSession(sessionId);
  // ... Ink components
};

Components

All components are exported for building custom UIs.

| Component | Purpose | | ------------------------ | --------------------------------------------------- | | Chat | Default conversational interface (block rendering) | | MessageList | Prop-driven message display (Static + in-progress) | | StreamingMessage | Live streaming response with cursor | | ToolCallIndicator | Spinner during tool execution | | ToolConfirmationPrompt | Y/N/A prompt for tools with requireConfirmation | | DiffView | Side-by-side diff display for file changes | | ErrorDisplay | Error box with optional dismiss | | InputBar | Visual-only text input (value + cursor from parent) | | CompletionPicker | Windowed completion list (emerald-themed) | | StatusBar | Container with context provider and layout | | DefaultStatusBar | Pre-composed status bar with responsive layout |

Status bar widgets (use standalone or inside <StatusBar>):

| Widget | Purpose | | -------------------- | ------------------------------------------- | | ModelInfo | Model name/id display | | TokenCount | Formatted token count (cumulative or tick) | | TickCount | Current execution tick number | | ContextUtilization | Utilization % with color thresholds | | StateIndicator | Mode label with color (idle/streaming/etc.) | | KeyboardHints | Contextual keyboard shortcut hints | | BrandLabel | Styled app name | | Separator | Visual divider between segments |

InputBar

Visual-only input display. Renders the current value and cursor position — all keystroke handling lives in the parent via useLineEditor.

import { InputBar, useLineEditor } from "@agentick/tui";

const editor = useLineEditor({ onSubmit: handleSubmit });

<InputBar
  value={editor.value}
  cursor={editor.cursor}
  isActive={chatMode === "idle"}
  placeholder="Type a message..."
/>

useLineEditor

Ink-specific wrapper around @agentick/client's LineEditor class. Provides readline-quality editing with cursor movement, history, kill/yank, and word navigation.

const editor = useLineEditor({
  onSubmit: (text) => send(text),
});

// In your centralized useInput handler:
if (chatMode === "idle") {
  editor.handleInput(input, key);
}

Returns { value, cursor, completion, completedRanges, handleInput, setValue, clear, editor }. Does not call useInput internally — the parent routes keystrokes to editor.handleInput when appropriate.

The editor property exposes the raw LineEditor instance for registering completion sources. The completion property is the current CompletionState | null — pass it to CompletionPicker to render the autocomplete picker.

For framework-agnostic usage (web, Angular), use LineEditor from @agentick/client directly, or useLineEditor from @agentick/react.

CompletionPicker

Renders a windowed completion list from CompletionState. Emerald-themed border, inverse highlight for the selected item, loading spinner, and "No matches" empty state.

import { CompletionPicker } from "@agentick/tui";

{editor.completion && <CompletionPicker completion={editor.completion} />}

Slash Commands

useSlashCommands provides a command registry with dispatch, dynamic add/remove, and completion integration.

import {
  useSlashCommands,
  helpCommand,
  exitCommand,
  createCommandCompletionSource,
} from "@agentick/tui";

const { dispatch, commands } = useSlashCommands([helpCommand(), exitCommand(exit)], {
  sessionId,
  send,
  abort,
  output: console.log,
});

// Wire into completion
useEffect(() => {
  return editor.editor.registerCompletion(createCommandCompletionSource(commands));
}, [editor.editor, commands]);

See COMPLETION.md for the full completion system reference.

handleConfirmationKey

Input routing utility for tool confirmation prompts. Maps y/n/a keys to confirmation responses.

import { handleConfirmationKey } from "@agentick/tui";

if (chatMode === "confirming_tool") {
  handleConfirmationKey(input, respondToConfirmation);
}

MessageList

Prop-driven message display. Accepts messages from useChat and splits them into committed (Ink <Static>) and in-progress (regular render) based on isExecuting.

<MessageList messages={messages} isExecuting={isExecuting} />

Chat uses useChat({ renderMode: "block" }) so messages appear block-at-a-time as content completes, rather than waiting for the entire execution to finish.

StatusBar

<StatusBar> is a container that calls useContextInfo and useStreamingText once, provides the data via React context, and renders a left/right flexbox layout with a top border.

Widgets read from context automatically when inside a <StatusBar>, or accept explicit props when used standalone.

Default — Chat renders <DefaultStatusBar> automatically:

Enter send | Ctrl+C exit                          GPT-4o | 6.2K 35% | idle

The default is responsive — hides token/utilization info in narrow terminals.

Custom — compose your own from widgets:

import { StatusBar, BrandLabel, ModelInfo, TokenCount,
  ContextUtilization, StateIndicator, Separator, KeyboardHints } from "@agentick/tui";

<StatusBar sessionId={sessionId} mode={chatMode}
  left={<KeyboardHints hints={{ idle: [{ key: "Tab", action: "complete" }] }} />}
  right={<>
    <BrandLabel name="myapp" />
    <Separator />
    <ModelInfo />
    <Separator />
    <TokenCount cumulative />
    <Separator />
    <ContextUtilization />
    <Separator />
    <StateIndicator labels={{ streaming: "active" }} />
  </>}
/>

Chat integration — control the status bar via the statusBar prop:

// Default (renders DefaultStatusBar)
<Chat sessionId="main" />

// Disabled
<Chat sessionId="main" statusBar={false} />

// Render prop — receives chat state
<Chat sessionId="main" statusBar={({ mode, sessionId }) => (
  <StatusBar sessionId={sessionId} mode={mode}
    left={<KeyboardHints />}
    right={<StateIndicator />}
  />
)} />

Architecture

The TUI reuses @agentick/react hooks unchanged. Ink is React for terminals, so the same useSession, useStreamingText, and useEvents hooks work in both browser and terminal.

For local agents, createLocalTransport (from @agentick/core) bridges the in-process App to the ClientTransport interface. The TUI components don't know or care about local vs remote.

createTUI({ app })
  → createLocalTransport(app) → ClientTransport
  → createClient({ transport })
  → AgentickProvider + Ink components
  → useSession, useStreamingText, useEvents (same as web)

For remote agents, the client uses HTTP/SSE to connect to the gateway. An eventsource polyfill is included for Node.js environments where globalThis.EventSource is not available.

Ink + React 19

Ink 5 bundles [email protected], which is incompatible with React 19. The monorepo applies a patch (patches/[email protected]) and overrides the reconciler to 0.31.0. See patches/README.md for details.