Skip to main content
Version: 0.20.0

Interface: InkChatOptions

Defined in: tui/ink/runChatInk.tsx:32

Options of runChatInk(): the chat's options plus the Ink-only ones.

Extends​

Properties​

PropertyTypeDescriptionOverridesInherited fromDefined in
agentLabel?stringShown once per turn, right before the agent's streamed reply text starts (not before any action lines that precede it) — and, when set, also colors that reply text via ui.agent(). Pass a pre-colored string (e.g. ui.agent("Captain Whiskers>")); omit to keep the plain, unlabeled/uncolored text streaming this kit had before.-ChatTuiOptions.agentLabeltui/chatTui.ts:37
exitCommands?readonly string[]Lines (trimmed, case-insensitive) that end the chat.-ChatTuiOptions.exitCommandstui/chatTui.ts:39
firstPromptSuggestion?stringThe suggestion shown (and taken with Tab) until the first turn starts: the SDK never suggests after the first turn, so without it the prompt is empty until the second reply.--tui/ink/runChatInk.tsx:96
formatAction?(toolName, input) => stringTurns a tool call into a one-line console label. Defaults to createFriendlyToolLabel() with no domain overrides — pass your own (e.g. createFriendlyToolLabel({ describe, extraLocalServers })) to cover a concrete agent's own domain-specific tools (Playwright's browser_*, etc.).-ChatTuiOptions.formatActiontui/chatTui.ts:26
formatResult?ResultFormatterThe line under a tool call for its result, e.g. a friendly one for an MCP tool whose output is written for the model: a string replaces the kit's (the result's first line), null hides it, undefined keeps it. Shown wherever results are ("full", or unfolded).--tui/ink/runChatInk.tsx:83
fullscreen?booleanTake the whole terminal (its alternate screen): the history scrolls in its own view above a prompt pinned at the bottom (PageUp/PageDown and the wheel scroll, Ctrl+End or typing goes back to the bottom), dragging selects text and a right-click copies it, and the terminal is left cleared on exit. Off by default.--tui/ink/runChatInk.tsx:50
header?HeaderInfoTitle, fields and an optional logo for the top of the chat: fixed at the top in full screen, printed once at the start otherwise. Not written to the session log.--tui/ink/runChatInk.tsx:37
historyLimit?numberMax entries kept in historyPath (and in the in-session ↑/↓ list). Defaults to 100.-ChatTuiOptions.historyLimittui/chatTui.ts:71
historyPath?stringWhen set, every non-empty line the human submits (including exit commands — a shell's own history keeps those too) is appended here as one JSON object per line ({ text: string, timestamp: string }, ISO 8601), trimmed to the most recent historyLimit entries (oldest dropped first). Loaded back at startup — including across separate runs of the same agent, since this path is normally a fixed file, not one under a per-run timestamped directory — into readline's own history, so ↑/↓ at the prompt cycles through prior prompts. Omit to skip persistence entirely (↑/↓ still works for the current session alone, via readline's own in-memory default).-ChatTuiOptions.historyPathtui/chatTui.ts:69
initialPrompt?stringWhen set, submitted as the very first turn — before the human is ever prompted — exactly as if they'd typed it themselves (mirrored to sessionLogPath/history like any other line). For an agent that should act proactively at the start of a chat (log into a site, load some state) instead of sitting idle at the prompt until the human says something first. Omit for the plain "wait at the prompt" behavior this kit had before.-ChatTuiOptions.initialPrompttui/chatTui.ts:48
language?stringThe language of the kit's texts ("en", "es", "fr", "de"). --language=<code> on the command line wins; without either, the one buildSessionOptions() chose from config.language, or else the system's.-ChatTuiOptions.languagetui/chatTui.ts:77
mode?ModeShown in the status bar.--tui/ink/runChatInk.tsx:41
modeControl?ModeControlThe session's mode control (buildSessionOptions() returns it): the status bar shows the current mode, Shift+Tab switches between the modes it allows ("guided", "interactive" and "plan"; an autonomous session can't switch), and entering or leaving plan mode is told to the model with the next message. With a session opener, the one it returns is used instead.ChatTuiOptions.modeControl-tui/ink/runChatInk.tsx:91
plain?booleanUse the plain readline chat (runChatTui()) even on a TTY.--tui/ink/runChatInk.tsx:43
promptLabel?stringShown before the cursor at each prompt.-ChatTuiOptions.promptLabeltui/chatTui.ts:30
promptSuggestions?booleanShow the model's predicted next prompt in the empty prompt, accepted with Tab (the SDK's promptSuggestions: after every turn but the first, from the parent's prompt cache). On by default; false turns it off.--tui/ink/runChatInk.tsx:56
renderApproval?RenderApprovalReplaces the default preview in the approval and manual-intervention panels.--tui/ink/runChatInk.tsx:39
runsDir?stringThe agent's runs folder, with a session opener in place of the options (e.g. (run) => buildSessionOptions(config, run.dir, spec, { run })): each run gets its own folder (<runsDir>/<timestamp>/) keeping its conversation, its session log (session.log, instead of sessionLogPath) and its transcript, and can be resumed: --continue on the command line starts with the latest run, and /resume lists them (date and the human's last message) to switch to one. The runs folder holds the whole conversation, tool results included and not redacted: keep it out of version control.-ChatTuiOptions.runsDirtui/chatTui.ts:87
sessionLogPath?stringWhen set, mirrors everything this loop prints — the welcome message, each prompt line the human types, the agent's streamed reply, action lines, and any error/warning — into this file as it happens (appended, plain text with ANSI color codes stripped), so a session leaves behind an exact, always-present transcript of what the terminal showed even when the agent never calls a single tool (unlike transcriptPath from buildSessionOptions(), which only gets written to on the first tool call). Omit to skip session logging entirely. With runsDir, the run's own session.log is used instead.-ChatTuiOptions.sessionLogPathtui/chatTui.ts:58
terminalIntegration?booleanShow the chat's state outside it (on by default): the tab title during a turn, the taskbar button's progress, and a mark on it when a turn ends while the window isn't focused (Windows Terminal). Also enables /copy, which copies the last reply.--tui/ink/runChatInk.tsx:62
theme?Partial<Theme>Colors for the kit's roles (see Theme), on top of the kit's defaults: only the roles given change, e.g. { toolResult: "yellow", selection: "#00ff00" }. One theme per process: without this option, the one already set stays.-ChatTuiOptions.themetui/chatTui.ts:106
toolDetail?ToolDetailHow much of the tool calls shows: "full" (the default), every call with its result line; "calls", the calls without their results, a failed one with a short line in the kit's language instead of the tool's error; "summary", one line per group ("Read 2 files, ran 1 shell command"). Ctrl+O unfolds any of them into the full view. For an audience that doesn't need the tools' raw output. The session log is the same whatever the level.--tui/ink/runChatInk.tsx:77
toolLabels?Readonly<Record<string, ToolLabel>>How the chat shows the extensions' tools (buildSessionOptions() returns them as toolLabels), before formatAction. With a session opener, the ones it returns are used instead.-ChatTuiOptions.toolLabelstui/chatTui.ts:100
toolPhrase?(toolName) => ToolPhrase | undefinedHow one of the agent's own tools counts in a folded group's summary, e.g. ["opened {n} page", "opened {n} pages"]; built-in tools have their own, and any other counts as "used {n} tools".--tui/ink/runChatInk.tsx:68
welcomeMessage?stringPrinted once before the first prompt, if given.-ChatTuiOptions.welcomeMessagetui/chatTui.ts:28