# How Apache Maka Ensures Consistency Across Desktop, TUI, and CLI Interfaces

> Discover how Apache Maka guarantees consistent behavior across Desktop, TUI, and CLI interfaces by centralizing execution on a single Runtime Host and sharing protocol definitions and rendering libraries.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-06

---

**Apache Maka treats its Desktop UI, Text-User Interface (TUI), and Command-Line Interface (CLI) as thin clients that delegate all execution to a single Runtime Host, ensuring identical behavior through shared protocol definitions, centralized UI messaging, and common rendering libraries.**

The Apache Maka project eliminates interface fragmentation by architecting all user-facing layers as lightweight renderers rather than standalone applications. Instead of duplicating business logic across three separate codebases, the Desktop, TUI, and CLI connect to a centralized Runtime Host that exclusively owns execution authority, model state, and session management. This architecture guarantees that tool results, error messages, and interactive behaviors remain pixel-perfect and semantically identical regardless of how users access the system.

## The Shared Runtime Host Architecture

At the foundation of Apache Maka’s consistency model lies the **Runtime Host**, a centralized process that handles all command execution and state persistence. Both the TUI and CLI establish connections to this `runtime-host` process, which serves as the sole authority for issuing commands, storing session state, and streaming results. Because the host broadcasts identical data to every connected client, the Desktop, TUI, and CLI interfaces observe the same tool outputs, session revisions, and intermediate processing states without implementation drift.

The communication contract is defined in [`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts), where message types, turn structures, and state update schemas are declared once and consumed universally by all front-ends.

## Unified UI Message Catalog

Human-readable copy—including labels, error messages, and guidance text—is centralized in [`packages/cli/src/tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-copy-catalog.ts) and consumed via the `resolveUiMessageCatalog` function. This approach guarantees that phrasing, tone, and localization remain synchronized across the TUI and CLI, even when rendered through different terminal libraries or desktop UI frameworks.

When either interface needs to display primary guidance, both resolve strings from the same catalog source:

```typescript
import { TUI_COPY_RESOURCES } from './tui-copy-catalog.js';
import { resolveUiMessageCatalog, defineUiMessageCatalog } from '@maka/ui';

const TUI_PRIMARY_GUIDANCE = resolveUiMessageCatalog(
  defineUiMessageCatalog<TuiPrimaryGuidanceCopy>()(
    TUI_COPY_RESOURCES['primary-guidance']
  )
);
const guidance = TUI_PRIMARY_GUIDANCE[locale];

```

## Common Rendering Primitives

Formatting logic for tool outputs, quiet previews, and redacted content is abstracted into shared core libraries and imported by both terminal and desktop layers. The `formatQuietPreview` function from `@maka/core/tool-quiet-preview` and redaction utilities from [`packages/core/src/display-redaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/display-redaction.ts) ensure that sensitive data masking and output formatting remain visually consistent whether displayed in a rich desktop panel or raw terminal output.

Both the TUI and Desktop renderer invoke these identical utilities, preventing formatting inconsistencies when presenting tool results or intermediate processing states.

## Protocol-Driven Turn Lifecycle

Every user interaction is encoded as a **Turn** object that the Runtime Host streams to attached clients. The TUI and CLI consume this stream through [`packages/cli/src/pi-tui-turn.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-turn.ts), processing identical turn data to render progress bars, streaming output, and final results. Because the turn lifecycle is protocol-defined rather than interface-specific, both clients display the same sequence of events during long-running operations.

```typescript
import { Turn } from '@maka/runtime-host-protocol';
import { piTuiTurn } from './pi-tui-turn.js';

function handleTurn(turn: Turn) {
  // Both TUI and CLI see the same Turn object
  piTuiTurn.process(turn);
}

```

## Session-Wide Context Synchronization

When global context changes—such as a new skill catalog deployment or session revision update—the TUI and CLI both invoke the refresh logic in [`packages/cli/src/tui-context-refresh.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-context-refresh.ts). This shared module pulls the latest host context and updates local client state, ensuring that autocomplete suggestions, available tools, and environment variables remain synchronized across interfaces without manual reconciliation.

## Identical Autocomplete and Guidance

Command completion behavior is standardized through shared token definitions in [`packages/core/src/skill-invocation-token.ts`](https://github.com/apache/maka/blob/main/packages/core/src/skill-invocation-token.ts). These definitions govern how the TUI and CLI parse and suggest skill invocations, preventing divergent autocomplete behavior between the terminal interface and the Desktop UI. By defining invocation syntax and token patterns once, Apache Maka ensures users experience consistent command patterns regardless of their chosen interface layer.

## Summary

- **Centralized Runtime Host**: All interfaces connect to a single `runtime-host` process defined in [`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts), ensuring unified execution authority and state management.
- **Shared UI Catalog**: The [`tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/tui-copy-catalog.ts) module provides localized, identical messaging to both TUI and CLI via `resolveUiMessageCatalog`, eliminating copy drift.
- **Common Rendering Layer**: Formatting utilities like [`tool-quiet-preview.ts`](https://github.com/apache/maka/blob/main/tool-quiet-preview.ts) and [`display-redaction.ts`](https://github.com/apache/maka/blob/main/display-redaction.ts) ensure consistent output formatting and redaction across Desktop and terminal.
- **Protocol-Based Turns**: The `Turn` object stream consumed through [`pi-tui-turn.ts`](https://github.com/apache/maka/blob/main/pi-tui-turn.ts) guarantees both interfaces display identical progress, streaming output, and final results.
- **Synchronized Context**: [`tui-context-refresh.ts`](https://github.com/apache/maka/blob/main/tui-context-refresh.ts) keeps session state, skill catalogs, and revision counters aligned across all connected clients.
- **Unified Token Definitions**: Skill invocation tokens defined in [`skill-invocation-token.ts`](https://github.com/apache/maka/blob/main/skill-invocation-token.ts) are consumed by both TUI and Desktop autocomplete systems, ensuring consistent command completion behavior.

## Frequently Asked Questions

### How does Apache Maka prevent the CLI and TUI from displaying different error messages?

Apache Maka centralizes all human-readable copy in [`packages/cli/src/tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-copy-catalog.ts) and resolves it through the `resolveUiMessageCatalog` function. Both the TUI and CLI import strings from this single source of truth, ensuring that error messages, labels, and guidance text remain byte-for-byte identical across all interfaces.

### Can the Desktop UI and TUI display different intermediate states during tool execution?

No. Both interfaces consume the same `Turn` object stream from the Runtime Host via [`packages/cli/src/pi-tui-turn.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-turn.ts). Since the host broadcasts identical turn data to every connected client, progress indicators, streaming tokens, and intermediate results remain synchronized across the Desktop UI, TUI, and CLI.

### Where does Apache Maka define the communication protocol between the interfaces and the Runtime Host?

The protocol definitions—including message types, turn structures, and state update formats—are codified in [`packages/runtime-host/src/protocol/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/index.ts). This file serves as the immutable contract between the Runtime Host and all client interfaces, ensuring that the Desktop, TUI, and CLI parse host messages with identical semantics.

### How does Apache Maka ensure redacted content looks the same in the terminal and Desktop UI?

Redaction logic and formatting utilities live in shared core packages such as [`packages/core/src/display-redaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/display-redaction.ts) and `@maka/core/tool-quiet-preview`. Both the TUI and Desktop UI import these exact functions, ensuring that sensitive data masking, quiet previews, and output formatting remain visually consistent across different rendering environments.