ink
Builds terminal chat UIs with @assistant-ui/react-ink and ANSI markdown with @assistant-ui/react-ink-markdown. Use when scaffolding `create --ink`, mounting `AssistantRuntimeProvider` around `useChatRuntime`, composing `ThreadPrimitive`, `ComposerPrimitive`, `MessagePrimitive`, `LoadingPrimitive`, `TextInput`, thread history, attachments, notifications, and terminal keyboard navigation, or when a chat needs grapheme safe editing, multiline display columns, an absolute backend URL, local file storage, or a custom `RemoteThreadListAdapter`. Route terminal markdown, tool output, message rendering, and Ink focus problems here. For browser application setup, web elements, and the standard web runtime, use [setup](../setup/SKILL.md).
assistant-ui · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add assistant-ui/skills --skill inkAbout this skill
name: ink
description: "Builds terminal chat UIs with @assistant-ui/react-ink and ANSI markdown with @assistant-ui/react-ink-markdown. Use when scaffolding create --ink, mounting AssistantRuntimeProvider around useChatRuntime, composing ThreadPrimitive, ComposerPrimitive, MessagePrimitive, LoadingPrimitive, TextInput, thread history, attachments, notifications, and terminal keyboard navigation, or when a chat needs grapheme safe editing, multiline display columns, an absolute backend URL, local file storage, or a custom RemoteThreadListAdapter. Route terminal markdown, tool output, message rendering, and Ink focus problems here. For browser application setup, web elements, and the standard web runtime, use setup."
license: MIT
assistant-ui Ink
Always consult assistant-ui.com/llms.txt for the latest API.
@assistant-ui/react-ink connects the assistant-ui runtime to Ink's terminal renderer. It shares runtime, tools, state, and AI SDK transport with web apps, but it has no DOM, CSS, or copied elements. Compose your screen from Ink's Box and Text plus the runtime aware primitives. @assistant-ui/react-ink-markdown renders assistant text as ANSI styled terminal markdown.
References
- ./references/primitives.md -- every terminal primitive namespace, its parts, scoped contexts, and the controlled
TextInput - ./references/hooks.md -- runtime, state, tool, notification, voice, and checklist hooks
- ./references/adapters.md -- file storage, attachment, and title adapters
- ./references/custom-backend.md -- local inference, local disk persistence, and backend thread ownership
- ./references/migration.md -- what transfers from a web app and what must be rebuilt for Ink
Start a terminal app
Scaffold the terminal example when starting fresh:
npx assistant-ui@latest create --ink my-app
cd my-app
--ink resolves to the with-react-ink CLI example. The example inventory also contains with-react-ink-web, but it is not the --ink scaffold target.
For an existing Node project, install the runtime, terminal renderer, and AI SDK transport together:
npm install @assistant-ui/react-ink @assistant-ui/react-ink-markdown ink react @assistant-ui/ai-sdk
The API route must run in a separate backend project. Unlike a browser app, a terminal process cannot use a relative /api/chat URL. Give AssistantChatTransport a complete URL that the process can reach.
import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
import { AssistantChatTransport, useChatRuntime } from "@assistant-ui/ai-sdk";
import { Box } from "ink";
import { TerminalThread } from "./components/terminal-thread.js";
const CHAT_API_URL = "http://localhost:3000/api/chat";
export function App() {
const runtime = useChatRuntime({
transport: new AssistantChatTransport({ api: CHAT_API_URL }),
});
return (
<AssistantRuntimeProvider runtime={runtime}>
<Box flexDirection="column">
<TerminalThread />
</Box>
</AssistantRuntimeProvider>
);
}
useChatRuntime and AssistantChatTransport come from @assistant-ui/ai-sdk. Its backend uses the AI SDK v7 UI message stream. See the runtime's AI SDK v7 guide for the route shape.
Compose a terminal thread
ThreadPrimitive.Messages creates the current message scope before each child runs. Read s.message inside the message component, then use Ink primitives rather than web elements. Use AuiIf for runtime state gates and LoadingPrimitive for the active run.
import { Box, Text } from "ink";
import {
AuiIf,
ComposerPrimitive,
LoadingPrimitive,
ThreadPrimitive,
useAuiState,
} from "@assistant-ui/react-ink";
import { MarkdownText } from "@assistant-ui/react-ink-markdown";
function Message() {
const message = useAuiState((s) => s.message);
const text = message.content
.filter((part) => part.type === "text")
.map((part) => ("text" in part ? part.text : ""))
.join("");
if (message.role === "user") {
return <Text color="green">You: {text}</Text>;
}
return (
<Box flexDirection="column" marginBottom={1}>
<Text color="blue">Assistant:</Text>
<MarkdownText text={text} />
</Box>
);
}
export function TerminalThread() {
return (
<ThreadPrimitive.Root flexDirection="column">
<AuiIf condition={(s) => s.thread.isEmpty}>
<Text dimColor>Send a message to begin.</Text>
</AuiIf>
<ThreadPrimitive.Messages>{() => <Message />}</ThreadPrimitive.Messages>
<LoadingPrimitive.Root gap={1}>
<LoadingPrimitive.Spinner variant="bar" />
<LoadingPrimitive.Text />
<LoadingPrimitive.ElapsedTime />
</LoadingPrimitive.Root>
<Box borderStyle="round" borderColor="gray" paddingX={1}>
<Text color="gray">{"> "}</Text>
<ComposerPrimitive.Input submitOnEnter placeholder="Message..." autoFocus />
</Box>
</ThreadPrimitive.Root>
);
}
The simple message example deliberately renders only text parts. Use MessagePrimitive.Parts when you need tool calls, attachments, data, sources, or reasoning. Its default terminal safe renderers handle those part types, and primitives shows the component map.
Terminal input behavior
ComposerPrimitive.Input is a composer bound TextInput. It is a controlled line editor, not Ink's nonexistent native input. submitOnEnter sends the current composer text. With multiLine, Enter inserts a newline unless submitOnEnter is enabled, in which case Shift Enter inserts a newline when the terminal distinguishes it. Ctrl J inserts a newline only in multiline mode and never submits a single line input.
- Left, Right, B