ARCANA
Back to Blog

Architecture

Desktop Integration: The Governance Bridge Between TUI and GUI

Jun 10, 2026 Architecture

Arcana runs in the terminal. But some decisions are easier in a GUI. The desktop governance bridge connects the TUI's permission system to a desktop application, letting you approve or reject agent actions with a visual interface.

The terminal is a powerful interface, but it has limits. A text-based approval prompt can tell you that the agent wants to edit a file, but it cannot show you a side-by-side diff. It can tell you the agent wants to run a command, but it cannot show you a preview of the output. For simple decisions, the terminal is fine. For complex ones, you want visual context.

The desktop governance bridge fills this gap. It connects the TUI's permission system to a desktop application that can render rich visual prompts: diffs, previews, metadata, and contextual information. The agent proposes an action in the TUI; the desktop app presents it with full visual context; you approve or reject in the GUI; the decision flows back to the TUI.

Why a Bridge?

Terminal permission prompts work, but they are limited. You cannot see a file diff in a TUI approval prompt. You cannot compare before-and-after states. You cannot click "approve all similar" in a terminal. The desktop bridge solves these limitations.

How It Works

When the TUI encounters a permission gate that benefits from visual presentation, it delegates to the desktop application:

  1. The agent proposes an action (file edit, git commit, network request)
  2. The TUI detects that a desktop bridge is available
  3. A visual prompt appears in the desktop app with full context (diffs, previews, metadata)
  4. You approve or reject in the GUI
  5. The decision propagates back to the TUI and the agent continues

DESKTOP_REQUIRED Gates

Some actions are too complex for terminal prompts. These are marked as DESKTOP_REQUIRED and cannot fall back to TUI approval. They must go through the desktop bridge. This ensures that complex decisions always get visual context.

Fallback Behavior

If the desktop bridge is not available (running on a headless server, for example), DESKTOP_REQUIRED actions block until the desktop is available or are queued for durable retry. The agent does not silently downgrade to a less-informed approval.

The Esc Gesture

In the TUI, pressing Esc while a permission gate is open interrupts the current action cleanly. This is part of the governance design: you can always say no, and saying no is as easy as pressing one key.

Configuration

The governance bridge is configured in your Arcana config file:

  • Linux / macOS: ~/.arcana/config.json
  • Windows: %USERPROFILE%\.arcana\config.json
{
  "governance": {
    "bridge": "auto",
    "desktopRequired": ["file-edit", "git-commit", "network-external"],
    "fallbackPolicy": "queue"
  }
}

The bridge setting controls when the desktop app is used:

  • "auto". Use the desktop bridge when available, fall back to TUI when not. This is the recommended default.
  • "always". Always require the desktop bridge. The agent blocks if the desktop is not running.
  • "never". Never use the desktop bridge. All approvals happen in the TUI.

The desktopRequired list specifies which action types must go through the desktop bridge regardless of the bridge setting. These are actions where visual context is essential for informed approval.

The fallbackPolicy controls what happens when a DESKTOP_REQUIRED action cannot reach the desktop:

  • "queue". The action is queued and retried when the desktop becomes available. The agent continues other work in the meantime.
  • "block". The agent pauses until the desktop is available. No other work proceeds.
  • "reject". The action is rejected. The agent receives a failure and can adapt.

Related Reading