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

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, 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 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:

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 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, 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.

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. 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. 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, ensuring unified execution authority and state management.
• Shared UI Catalog: The 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 and 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 guarantees both interfaces display identical progress, streaming output, and final results.
• Synchronized Context: 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 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 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. 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. 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 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.

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