rossum-agents: Command for Claude Code

Ink TUI Best Practices

Comprehensive guide for building high-quality terminal user interfaces with Ink v5, React 18, and TypeScript. Covers layout, streaming, performance, accessibility, and AI chat UI patterns.

When to Apply

Reference these guidelines when:

• Writing or reviewing Ink/React terminal UI components
• Implementing SSE streaming or real-time data display
• Designing keyboard navigation and focus management
• Optimizing TUI rendering performance
• Building AI chat interfaces (tool calls, thinking, streaming responses)

---

1. Ink Fundamentals

Layout Rules

Rule	Detail
All text in <Text>	Raw strings inside <Box> throw errors
<Box> = flex container	Every <Box> is display: flex by default (Yoga layout engine)
<Text> contains only text	Never nest <Box> inside <Text>
Default direction	flexDirection="row" — use "column" for vertical stacking
Percentage widths	<Box width="70%"> works for fluid layouts
No native scrolling	overflow="hidden" clips but doesn't scroll — implement virtual windowing manually

Layout Patterns

// Vertical stack with spacing
<Box flexDirection="column" gap={1} padding={1}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
</Box>

// Horizontal with space distribution
<Box justifyContent="space-between" width="100%">
  <Text>Left</Text>
  <Spacer />
  <Text>Right</Text>
</Box>

// Fixed footer with flexible content
<Box flexDirection="column" height={rows}>
  <Box flexGrow={1} flexDirection="column" overflow="hidden">
    {/* Scrollable content */}
  </Box>
  <Box height={3} borderStyle="single">
    <Text>Status bar</Text>
  </Box>
</Box>

Text Wrapping

<Text wrap="truncate"> prevents long text from breaking layouts. Options: "wrap" (default), "truncate", "truncate-start", "truncate-middle", "truncate-end".

---

2. Hooks

useInput — Keyboard Handling

useInput((input, key) => {
  if (key.return) handleSubmit();
  if (key.escape) handleCancel();
  if (input === "q") exit();
  if (key.ctrl && input === "d") scrollDown();
}, { isActive: isFocused }); // Gate handler with isActive