Documentation / @agentick/tui

@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

typescript

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:

typescript

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:

typescript

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:

typescript

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 }:

typescript

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
`SessionTree`	Tree view of spawned agents with per-agent activity
`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.

typescript

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.

typescript

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.

SessionTree

Tree view of spawned agents. Subscribes to the root session's events and routes tool activity to the correct spawn via spawnPath. Shows a compact tree with box-drawing characters, per-agent tool counts, and current tool activity.

typescript

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

<SessionTree sessionId={sessionId} />

Automatically hides when no spawns exist. Completed spawns remain visible for 3 seconds, then the tree clears. Pair with ToolCallIndicator — SessionTree shows the spawn graph, ToolCallIndicator shows the root session's tools.

useSessionTree

Hook that builds a SessionTreeState from stream events. Single subscription to the root session — child events are routed via spawnPath[0].

typescript

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

const tree = useSessionTree(sessionId);
// tree.spawns — SessionTreeNode[] with status, currentTool, toolCount
// tree.hasActive — whether any spawn is still running
// tree.rootTool — current tool on the root session

CompletionPicker

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

typescript

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.

typescript

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.

typescript

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.

typescript

<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:

typescript

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:

typescript

// 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 react-reconciler@0.29, which is incompatible with React 19. The monorepo applies a patch (patches/ink@5.2.1.patch) and overrides the reconciler to 0.31.0. See patches/README.md for details.

@agentick/tui - Terminal UI for Agentick

Ink-based terminal UI that reuses @agentick/react hooks. Works with both local (in-process) and remote agents.

Examples

typescript

import { createApp } from '@agentick/core';
import { createTUI } from '@agentick/tui';

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

typescript

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

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

typescript

import { createTUI } from '@agentick/tui';
import { MyDashboard } from './my-dashboard.js';

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

knob

Functions

@agentick/tui ​

Installation ​

@agentick/tui

Installation