Skip to main content

Use mecatui

mecatui is Mecatl's interactive terminal client. It is a skin over the shared agent/server core: bare mecatui hosts an embedded mecated server in the same process, while mecatui connect ADDRESS displays and controls a server that is already running.

Use it to work with sessions, switch models, approve actions, inspect tool calls, and monitor delegated work. The detailed mecatui section owns the client workflow and controls; this page is the feature-level entry point.

Choose how to connect​

  • Local work: run mecatui to start an embedded server over a private local socket. The embedded server uses local credentials, workspace, storage, and policy configuration.
  • Client/server deployment: run mecatui connect ADDRESS when an operator has already started mecated or mecak8s. The remote server owns the workspace, credentials, storage, capabilities, and policy; local embedded-server settings do not apply.

A loopback connect can select an absolute path interpreted on the server host. For a non-loopback target, mecatui sends no cwd and rejects --workspace; the server's listener authority chooses its configured root or no-FS profile. Neither mode uploads or shares a checkout from the computer running the TUI.

Start here for connection ownership, TLS, bearer authentication, and remote workspace rules: Connect to a server.

Common workflow​

# Start an embedded session in the current checkout.
mecatui --workspace "$PWD"

# Or seed its first prompt while keeping the session interactive.
mecatui --workspace "$PWD" \
  --prompt "Summarize the failing tests in this repository"

The TUI can browse and continue stored sessions, switch models without losing the visible conversation, approve permission requests, steer a running session, and launch a dedicated debugger when the connected server supports it:

mecatui debug TARGET
mecatui connect ADDRESS debug TARGET

TARGET accepts an exact full opaque session ID—including the exact final ID printed on exit—or the displayed 12-column short handle. Safe [A-Za-z0-9._-] bytes are literal except that a leading - is encoded as %2D; other UTF-8 bytes are uppercase %HH atoms, and only complete atoms that fit are shown. The literal has no leading #. A syntactically valid short target consults the complete caller-visible inventory. Exact full-ID equality wins; otherwise one unique projected match resolves. On ambiguity, open /session, copy the full exact ID, and pass it as TARGET through the same command. If inventory cannot be loaded or no handle matches, mecatui sends TARGET unchanged and reports the server's ordinary exact-ID authorization/not-found result. It creates a separate no-filesystem analysis session and is explicit consent to send bounded stored-session evidence—which may include secrets—to the selected model. It never resumes or mutates the target. Its bounded network view can correlate persisted, sanitized retry/transport evidence to that target without exposing raw errors or request data. See Sessions.

Use the dedicated guides for those workflows:

  • Getting started — launch a local session and submit a first prompt.
  • Sessions — browse, inspect, continue, fork, and maintain chats.
  • Using the TUI — streaming, steering, approvals, and model switching.
  • Commands and memory — learning, reflections, and memory-maintenance commands.

Keyboard help​

Press ? on an empty prompt to open the keys-and-features overlay. When the overlay is taller than the conversation area, use Up/Down to move one line, Page Up/Page Down to move a page, and Home/End to jump to the beginning or end. The overlay shows its current line range; press ? or Esc to close it. The displayed key labels and capability availability reflect the active client keymap and connected server.

Configuration ownership​

Client settings such as themes, keymaps, terminal rendering, and mouse behavior belong to mecatui. Provider selection, posture, workspace trust, tools, storage, and other agent behavior belong to the embedded or connected server.

For embedded-server flags, see Run mecated standalone. For model selection, see Choose models and providers. For permissions and trust, see Permissions and posture.

Limitations​

  • connect never discovers or starts a server and does not fall back to embedded mode.
  • A connected server may expose different tools, models, media capabilities, and storage features than an embedded server.
  • Remote clients cannot use the TUI host's local files unless those files are available in the server's workspace namespace.
  • TLS, authentication, and server-side policy are configured at the server boundary; mecatui cannot override them locally.

Next steps​