How Mako Renders Conversation State in Its Terminal UI (TUI): A Deep Dive into the Transcript Pipeline

Mako visualizes conversation state by converting immutable transcript turns into formatted text rows through a three-stage pipeline involving entry memoization, document aggregation, and terminal viewer output.

Mako's Terminal UI (TUI) transforms internal conversation history into live terminal displays using a specialized rendering architecture. This examination of the Apache Mako codebase reveals how the project structures its conversation state visualization, from low-level text formatting in pi-transcript.ts to the final screen draw orchestrated by the TUI runner.

The Three-Stage Rendering Architecture

Mako implements a unidirectional data flow for conversation rendering. The pipeline processes immutable MakaPiTranscriptEntry objects through three distinct layers before they appear on screen.

Stage 1: Transcript Entry Formatting in pi-transcript.ts

The foundation resides in packages/cli/src/pi-transcript.ts, where each conversational turn undergoes individual formatting. The renderTranscriptEntryMemoized function wraps the heavy formatting logic and caches results for efficiency, calling renderTranscriptEntryBlock to handle line wrapping.

// From packages/cli/src/pi-transcript.ts
function renderTranscriptEntryMemoized(
  entry: MakaPiTranscriptEntry,
  width: number,
  fullyOffScreen: boolean,
): string[] {
  const lines = renderTranscriptEntryBlock(entry, width);
  // ...additional post-processing...
  return lines;
}

The PiTranscript class exposes createDocumentRenderer(), which aggregates these per-entry functions into a callable that produces the full conversation document for a given terminal width.

Stage 2: Document Renderer Creation in pi-tui-runner.ts

The orchestration layer in packages/cli/src/pi-tui-runner.ts instantiates the rendering pipeline. The runner creates a transcript instance and obtains a document renderer that it invokes during each render cycle.

// From packages/cli/src/pi-tui-runner.ts
const transcript = new PiTranscript(...);
const renderTranscript = transcript.createDocumentRenderer();

// During a render cycle:
const lines = renderTranscript(currentTerminalWidth);

This renderer returns a complete, line-by-line representation of the conversation, handling role labels, timestamps, and text wrapping according to the current terminal dimensions.

Stage 3: TUI Integration via pi-tui-transcript-viewer.ts

The presentation layer in packages/cli/src/pi-tui-transcript-viewer.ts bridges the document renderer to the terminal screen. The PiTuiTranscriptViewer class implements the renderTranscript(width: number): readonly string[] interface, consuming the prepared lines and preparing them for the TUI layout engine.

// From packages/cli/src/pi-tui-transcript-viewer.ts
export class PiTuiTranscriptViewer {
  renderTranscript(width: number): readonly string[] {
    const document = [...this.input.renderTranscript(width)];
    // The viewer may add UI framing or gutter decorations here
    return document;
  }
}

The viewer fetches formatted content via this.input.renderTranscript(safeWidth), returning an array of strings that the terminal driver draws during each render tick.

Performance Optimization Through Memoization

Mako optimizes TUI responsiveness through strategic memoization. The renderTranscriptEntryMemoized function caches formatted output for individual transcript entries, ensuring that only new conversation turns trigger recomputation during live updates.

When the TUI render loop invokes the document renderer on every tick (or upon terminal resize), the underlying memoized functions skip processing for previously rendered entries. This design maintains high frame rates even with lengthy conversation histories, as the system recomputes only the delta between render cycles.

Live Update Mechanism

The PiTuiRunner orchestrates the live conversation display by continuously invoking the document renderer. As new MakaPiTranscriptEntry objects append to the immutable transcript, the renderer automatically incorporates them into subsequent output arrays.

The pipeline handles dynamic terminal resizing gracefully. When width changes occur, the runner passes the new safeWidth parameter to renderTranscript(), triggering fresh line-wrap calculations for the entire conversation history while preserving the memoization benefits for text content that hasn't changed.

Summary

• Immutable transcript storage: Conversation turns exist as MakaPiTranscriptEntry objects in pi-transcript.ts, providing a durable history that feeds the rendering pipeline.

• Memoized formatting: The renderTranscriptEntryMemoized function caches individual entry formatting to minimize CPU overhead during live TUI updates.

• Document aggregation: createDocumentRenderer() in the PiTranscript class assembles formatted entries into complete line arrays sized for the current terminal width.

• Viewer abstraction: PiTuiTranscriptViewer exposes the renderTranscript() API that delivers readonly string arrays to the terminal driver, enabling UI framing and decoration layers.

• Continuous rendering: The TUI runner invokes the pipeline on every render cycle, ensuring new conversation turns appear instantly while leveraging caching for performance.

Frequently Asked Questions

What data structure stores conversation turns in Mako?

Mako stores conversation turns as MakaPiTranscriptEntry objects within the PiTranscript class. These entries contain role labels, timestamps, and message content, feeding into the renderTranscriptEntryMemoized function for display formatting.

How does Mako optimize transcript rendering performance?

Mako implements memoization at the entry level through renderTranscriptEntryMemoized, which caches formatted line arrays for individual transcript entries. This ensures the system only recomputes formatting for new turns rather than reprocessing the entire conversation history on every frame.

Which component handles the final terminal output formatting?

The PiTuiTranscriptViewer class in packages/cli/src/pi-tui-transcript-viewer.ts handles final output preparation. It implements the renderTranscript(width: number): readonly string[] interface, returning an array of formatted strings that the terminal driver draws directly to the screen.

Can the transcript viewer handle dynamic terminal resizing?

Yes, the architecture supports dynamic resizing through the width parameter passed to renderTranscript(). When terminal dimensions change, the TUI runner invokes the document renderer with the new safeWidth, triggering fresh line-wrap calculations while preserving memoized text content for unchanged entries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}