Browse documentation

Technical documentation / Reference

Mission Control TUI

Mission Control user guide · Technical reference index · Repository README

Use Mission Control to edit prompts, follow tools and subagents, inspect captured output, and change settings without leaving the terminal.

magi-code
magi-code --prompt "Summarize this repository."

Mission Control is the conversation interface. Both stdin and stdout must be TTYs. --prompt rejects whitespace-only input.

Startup and readiness

You can edit after the first frame, before execution is ready. Settings, instructions, skills, and session setup load before that frame. Background session cleanup does not block readiness.

Execution waits for the selected primary agent, enabled subagent profiles, and every enabled MCP server. A failure in any required component blocks queued work. Unselected or disabled profile errors only warn. Autocomplete, titles, and Git metadata do not block execution. See MCP startup.

Startup prompt queue

During readiness, you can queue one normal prompt. The queued prompt becomes immutable, and the editor clears for a separate draft. A second submission is rejected without replacing either. Alt-C cancels the queue and preserves the draft. /help and /quit work immediately; other slash commands remain blocked until ready.

After readiness, an input fence checks for later queue decisions, then runs the prompt once. An untouched --prompt follows the same path. A critical startup failure restores the terminal, exits nonzero, and does not run the queue. Startup queuing is separate from active-run steering.

Provider connection

/login opens Connect Provider at 60% terminal width and 40% height. It lists OpenAI Codex, Anthropic, Claude Subscription, OpenAI, and Custom Provider with current status. Select with Up/Down, then Enter. Enlarge compact terminals when prompted to reveal editable controls.

Edit settings

/settings opens six task groups, plus Search and Browse every setting. Beta features shows an overview when beta is off and grouped PSM/Jev settings below the opt-in toggle when on. Preferences—including availability lists—share one Global/Project draft. Ctrl-S saves, Ctrl-G changes scope, and Tab selects Review/Save/Discard. Dirty close or scope changes offer Save/Discard/Stay. F1 shows full help. Catalog refresh, skill rescan, cache deletion, and MCP approvals remain separate operations. See Configuration for controls and application timing.

Compaction, Side agent, Summary, Session titles, PSM, and Images each use one paired provider/model picker. It lists enabled cached models, including unsaved availability edits. Enter accepts into the draft; Esc cancels. Opening the picker does not refresh catalogs.

Side conversation

/side opens an independent conversation, including during primary work. It has separate history and display state but uses the same transcript cards, prompt editor, and activity inspection. Esc hides it without stopping work; /side reopens it. Alt-C cancels only side work. Hidden work shows running/unread status at top right.

Inside the modal, /model or Alt-M selects the side model and Alt-T cycles its thinking level without changing the primary conversation. Changes require an idle side agent. /reset preserves old history and waits for worker/MCP cleanup before creating a new UUID session with configured defaults. The live conversation lasts only for this process. Its files live under sessions/side/, outside primary session selection. --no-session disables it. See Side agent for tools, shared-file risks, settings, and lifetime details.

Prompt editing and paste

Enter submits. Shift-Enter, Ctrl-J, and Ctrl-Enter insert a newline. Use Ctrl-J as the portable fallback. Some terminals send Shift-Enter and Ctrl-Enter as plain Enter, causing submission. This includes WSL when its host terminal or an intervening multiplexer drops these modifiers.

Autocomplete and modals take precedence over editing. The prompt grows from 1 to 5 visual rows. Use cursor keys for longer prompts; mouse-wheel events over Prompt do nothing.

Paste normalizes CRLF and lone CR to \n, keeps tabs/newlines, and strips other C0 controls, ESC, and DEL. Explicit Crossterm Event::Paste and the Windows text-burst fallback share this policy. At least 3 logical lines or more than 800 UTF-8 bytes collapse to [Pasted #N · X lines]. Text starting with / after optional whitespace or with ! remains ordinary text so commands still work. Thresholds are fixed.

The expanded normalized prompt, including hidden paste payloads, is capped at 1 MiB. An oversized edit is rejected in full with Prompt is limited to 1 MiB; edit rejected; it is not truncated.

Collapsed pastes act as one unit during cursor movement, deletion, selection, mouse hit-testing, and undo/redo. Submission, selected copy, restored history, and provider input use the full normalized payload. Rejected submissions restore label and payload together. Autocomplete sees only visible text and offsets. Labels contain only local IDs and line counts, while debug output excludes payloads. Typed text resembling a paste label remains ordinary text.

Alt-V reads the local desktop clipboard while primary or side Prompt is focused: supported image first, otherwise text. Subagent steering editors do not handle this shortcut. Clipboard access and PNG encoding run in one owned background worker per conversation. Ordinary terminal paste stays unchanged. macOS terminals must send Option as Alt/Meta; otherwise Option-V types √. Native Linux Wayland requires compositor data-control support; X11/XWayland is also supported. SSH does not forward the client clipboard; WSL needs access to a supported desktop clipboard.

Images are saved under resolved $MC_HOME/tmp (default ~/.magi-code/tmp) as unique clipboard-image-N-UUID.png files. Unix directory/file permissions are 0700/0600; symlinked tmp directories are rejected. Images must contain valid RGBA data, fit 16 megapixels, and encode within capabilities.tools.view_image.max_image_bytes. Labels use the editor's shared paste numbering: [Pasted Image #N] expands to [View the image here: /absolute/path.png]. Submitted chat and replay project these references back to labels without changing stored/provider text. The model can inspect the file with view_image; outside-project access settings still apply.

Submission waits for pending paste, for up to five seconds. Timeout leaves the draft unchanged and allows submission, but another clipboard request must wait for the old worker to finish; side reset also waits for that worker. If the draft, cursor, selection, or session changes before completion, paste is discarded; press Alt-V again. Saved files remain after exit, including discarded pastes, so resumed sessions retain their image references. No automatic cleanup runs; remove files manually only when their session references are no longer needed.

Editor limits

Undo history retains 50 edits. A collapsed paste counts as one edit and restores its full payload. Non-empty selections copy through OSC52.

Movement is character-based, not guaranteed grapheme-safe. Extremely long prompts can exceed the editor's 65,535-row display coordinates, affecting cursor placement and mouse selection even though logical text is retained. Use smaller prompts in that case. Mouse-wheel scrolling is disabled over Prompt; use cursor keys.

Follow activity

Transcript occupies the body beside the tab rail. Shift-Tab or a rail click switches between Transcript and Changes without removing Prompt. The header shows session and branch information plus panel controls.

Bash, Code Mode, and Read transcript cards hide detailed metadata rows. Bash keeps its command and exit status; Code Mode keeps its outcome summary and recent calls; Read keeps resource paths. Execution metadata, stored history, provider results, and local-agent card facts remain unchanged.

Header row 1 shows [Alt+] Panels • [Alt-A] Pin. Clicking **Panels** or pressing Alt-` shows or hides a small card below the header listing **Activities** (Alt-1), **Session Files** (Alt-2), **AI Summary** (Alt-3), and **Background Jobs** (Alt-4); [•] marks open panels and clicking a row toggles that panel. Esc or a click outside hides the card. Alt-1–Alt-4` work whether the card is shown or not. Panels overlay the right side by default, at one third of transcript width with a 27-column minimum where space permits. Panels stack in opening order and share the available height. Closing one expands the others; reopening puts it last.

Pin (Alt-A) reserves a column beside Transcript instead of covering it:

Esc closes a focused unpinned panel, or the last opened panel when none has focus, after dismissing autocomplete. Pinned panels ignore Esc; use their Alt shortcut or close button. Other dialogs take priority.

Panel order, visibility, and pinning survive session switches and application restarts through global interface.tui.panel_layout. Focus and scroll are not saved across restarts. These preferences never enter history or provider requests.

Letters, numbers, /, or clicking Prompt return focus to it without closing panels. Tab cycles Prompt and Transcript; pinned panels join that cycle in opening order. Clicking a panel focuses it without moving it. Navigation keys act on the focused panel; the mouse wheel scrolls the hovered pane.

In Activity Tree, arrows select or expand rows; Enter opens detail. Ctrl-T also opens the tree. Session Files uses arrows and Page Up/Down to scroll. In Summary, Enter starts or stops generation. Hiding Summary does not stop it.

In Changes without overlays, Tab cycles Prompt, Files, Original, and Diff; Shift-Tab returns to Transcript. See Diff review for line comments, refresh behavior, storage, and provider visibility.

The prompt border shows run status, provider/model, thinking level, and primary-agent selection. Its footer shows active session time, input/output usage, cache share, estimated context, and the compaction threshold.

Usage totals include primary and child activity and survive resume and compaction. Cache share is cached input divided by total input. Missing updates retain the last known percentage; older unrecorded usage cannot be recovered.

Session time includes foreground provider waits, tools, retries, Bash Mode, manual compaction, and cancellation cleanup. Concurrent child time is not added twice. Idle time and background title/summary work are excluded. An abrupt exit may lose the unfinished interval.

The context bar measures the primary agent's estimated input against its window; | marks automatic compaction. It is not an exact countdown. Disabled compaction shows Auto off; unknown context shows a placeholder. Narrow layouts omit the bar before clipping text.

The prompt border shows Claude and Codex subscription usage whenever their accounts are connected, regardless of the selected provider or model. Both indicators show percentage used. Connected accounts without quota data show usage unavailable instead of disappearing.

Claude prefers the five-hour window, falling back to the weekly window. Codex Pro prefers the weekly window; other plans prefer five hours. A missing preferred Codex window falls back to an available one. Claude's five-hour window and Codex's windows show a reset countdown when available.

Background refresh runs at most every five minutes during or shortly after agent work. Missing quota data also retries while idle; failed Claude loads retry after 60 seconds. /usage requests fresh data. Keyboard and mouse activity alone do not refresh known quota. Each completed claude-subscription request also updates Claude quota from Anthropic's rate-limit response headers. Failed Codex auth reads hide its indicator; Claude hides its indicator after three consecutive failed status probes.

Tool cards show status and bounded, sanitized summaries. Write/edit cards update in place; a successful hash_edit previews at most four changed lines. Use activity detail for captured output and metadata.

Kitty, Ghostty, and Herdr can show local image previews in view_image cards and completed assistant Markdown. Other terminals keep text. Remote URLs and data URLs are never loaded.

Inspect complete tool output

Click an activity tree row or select it with Up/Down and press Enter to open Selected Activity Detail in a modal. Escape closes it and returns focus to the tree. Up/Down, Page Up/Down, and the mouse wheel scroll details without scrolling the panes behind it. Background clicks, typing, and pane shortcuts are blocked while it is open. Left/Right in the tree still collapse/expand activities.

Selected Activity Detail has Status, Tool • <actual name> • <label>, Metadata / Params, and Sanitized Output. A successful live hash_edit may add Applied Diff. Click ▸ Metadata / Params (or other activities' ▸ Metadata) to expand; click ▾ to collapse. Selecting another activity resets it to collapsed.

Detail retains all submitted parameters and result-metadata fields with recursive credential redaction and terminal-control sanitization. Output is complete up to each tool's native capture limit; expanded metadata retains truncation details. Parent subagents output is not compacted here. Applied diffs are display-only and absent after session hydration.

The rail's Diff page reviews current worktree changes against HEAD. Tool-specific diffs remain in activity detail; branch status, #git-status, and Git-aware autocomplete remain available.

Follow subagents

Live subagent cards show aggregate settled/running/failed/waiting counts, clickable task chips, selected intent, recent activity, and [View Subagent ↗]. interface.tui.subagent_card_rows controls recent activity rows: default 16, range 1 to 50.

Chips prefer configured agent names, falling back to task identity. The selection also shows identity and resolved provider/model/reasoning when available. The first task is selected initially; selecting a chip keeps that task selected until another chip is chosen. Activity updates do not switch tasks. View Subagent opens a live viewer for that task and its batch siblings, with tabs and bounded timeline scrolling. Closing leaves the underlying selection/scroll unchanged. Stalled tasks suppress late start events after terminal failure. Selection, scrolling, and drafts remain local display state.

The viewer's bottom prompt uses the primary prompt's styling and keyboard editor, including selection, undo/redo, multiline input, and collapsed paste. Each task keeps a separate draft. Autocomplete offers only $skill tags; slash commands are rejected, and a leading ! is literal steering text, never a shell command. Mouse editing is not supported in this prompt.

Completed children are read-only, but Alt-C can still recall unconsumed steering. Failed or cancelled children retain pending input for recall during the current application session; a new primary run is blocked until it is recalled. Accepted steering uses the child's existing continuation and persistence path, not a separate run. See compaction and steering.

Show hooks and injected context

automation.hooks.show_in_tui=true shows matching before/after hooks under their tool with running/success/failure status and sanitized phase/label/tool metadata. Default false keeps successful hooks quiet.

Provider-injection visibility uses separate automation.hooks.injected_content settings: show_in_transcript adds local/system rows; show_in_activity_tree places rows under the related tool/message, or at the root. Both default to false. style defaults to content (redacted/truncated text); metadata shows only label, status, item count, and byte count. These settings affect display only and do not enable injection itself.

Direct shell commands

Submit !command with ! as the first character to run immediately through guarded bash in cwd, without a provider request or authentication. Tool restrictions, hooks, and cancellation still apply. Command and output are local display only, not durable session history. See direct shell execution.

Autocomplete

Updates

After the first frame and every four hours, a bounded background check announces newer stable crates.io versions. /update requires idle state, leaves the TUI for Cargo's build output, and reopens the exact session only after cleanup and a successful update. It never replays the initial prompt. See Installation and updates for platform behavior, supported installations, and recovery.

/restart uses the same idle-only cleanup and session handoff without running Cargo. It reopens the current executable, including source builds, and reloads startup settings. See Restart without updating.

Fast mode

/fast [on|off|status] and /ultrafast [on|off|status] select mutually exclusive global speed modes while idle. A bare command toggles its mode; enabling the other selects it, and either command's off restores Standard. Neither switches models. Status and invalid usage work during a run. Writes share the existing worker off the UI loop; memory changes only after disk success. Pending writes block another mutation, new prompt, or compaction and restore input, while status/help/quit stay usable. Accepted writes settle during cleanup. The startup snapshot is authoritative and successful writes update it for later work.

An unacknowledged persistence-worker failure with no event blocks retry until restart. A delivered failure clears when its matching event is handled.

Fast and Ultrafast highlight the provider/model label instead of showing a separate speed marker. Use /fast status or /ultrafast status to inspect the requested mode. Fast eligibility follows Codex catalog/fallback rules or explicit custom-provider fast_mode metadata; Ultrafast requires catalog-advertised Codex support. See Configuration. Both apply to eligible primary turns, subagents, and blocking compaction, not title requests. Color terminals animate only provider/model text right-to-left in rainbow colors about every 83 ms: Fast advances one color step, Ultrafast two for twice the movement speed without more redraws. Reduced motion disables animation; without color, bold and underline mark the label. Thinking, context, separators, spaces, and hotkeys keep normal styles. Alt-M is hidden during a run while animation stays paced.

Switch or export a session

/sessions shows newest-first sessions, marks the current one, and previews the selection in a second column when space allows. Bounded reads find first and most recent conversational user/assistant messages; tool-only, hook, context-cache, title, and diagnostic events are ignored. Preview text is sanitized/redacted.

Tab/terminal-delivered Shift-Tab switches list/preview focus; arrows move the list or scroll the preview. Wheel scrolls the hovered column, Enter switches from either focus, and Esc closes without switching.

/export requires an idle run and active persisted session. It rejects arguments and duplicates, runs off the UI loop, and writes a private ZIP under $MC_HOME/exports without overwriting. Completion appears in normal status and is ignored if it belongs to a session changed during export. The unencrypted archive contains raw session data and a manifest and may be sensitive; see export contents and safety.

Exit and cleanup limits

The terminal is restored before worker cleanup. Cancellation is requested first; each critical startup/provider worker gets a 2 s join before detach/error. Non-cooperative detached workers may still have side effects. Decoration gets only a short grace before detach. Accepted Fast persistence has no fixed total join bound if filesystem work stalls after lock acquisition. Export workers are cancelled and joined so publication cannot continue after teardown.

In-flight blocking HTTP MCP POST/body operations, including notifications/initialized, cannot be interrupted. A worker detached after 2 s may remain in that call until the configured timeout (default 30 s, maximum 300 s). Cancellation before request start and stdio/pending-response paths remain responsive.

Controls

KeyAction
EnterSubmit from Prompt, queue during startup, or accept visible autocomplete.
Shift-Enter / Ctrl-EnterInsert a newline when the terminal preserves modifiers; otherwise use Ctrl-J.
Ctrl-JInsert a newline (portable fallback).
Left / RightMove the prompt cursor by character.
Up / DownMove cursor vertically in Prompt; otherwise move selection/scroll by focused pane or modal.
Mouse wheel over PromptIgnored; use cursor keys.
Ctrl-Z / Ctrl-YUndo/redo in Prompt; OAuth uses Ctrl-Y to copy its URL.
Alt-OOpen the OAuth URL during provider connection.
Ctrl-Left / Ctrl-RightMove by word.
Ctrl-Backspace / Ctrl-DeleteDelete previous/next word.
Shift-ArrowExtend prompt selection.
Ctrl-ASelect all prompt text.
Ctrl-CCopy non-empty selection through OSC52; otherwise clear input, or exit if empty.
Alt-VPaste local clipboard image, otherwise text, into focused Prompt.
Ctrl-DExit.
Alt-PCycle primary agent selection.
EscFocus Prompt, close help/unpinned modal, or cancel a modal action; pinned column modals and provider Saving cannot be closed with Esc.
TabCycle Prompt/Transcript, including open pinned modals; in Changes without overlays, Prompt/Files/Original/Diff; accept autocomplete; move dialog focus.
` Alt- ``Show/hide the header Panels menu.
Alt-1 / Alt-2Show/hide Activities / Session Files.
Alt-3 / Alt-4Show/hide AI Summary / Background Jobs.
Alt-APin/unpin all column modals beside Transcript; pinned modals are hidden on Changes.
Shift-TabSwitch Transcript/Changes; pinned modals hide on Changes without closing. Other dialogs retain their own controls.
Ctrl-TOpen Activity Tree.
F1 or /helpToggle/open help.
Alt-E / Alt-CExpand/collapse activities; during startup Alt-C cancels the queue; during a run it restores queued steering for editing, or requests cancellation when none is queued. Never submits editor text.
Alt-F / Alt-RSelect first failed/running activity.
Left click / dragPosition/select prompt text; elsewhere select transcript text, disclose metadata, or use subagent controls. Live viewer consumes mouse input: wheel scrolls and clicks switch sibling tabs.
Terminal pasteApply the normalization, collapse, and byte-limit rules above.

With steering queued, the prompt border shows [Alt-C] to edit steering. Alt-C removes all queued messages and restores them to the prompt in queue order, separated by newlines, followed by any existing draft. The run continues. If the combined text exceeds the prompt limit, the queue and draft remain unchanged. With no steering queued, the border shows [Alt-C] to cancel. Cancellation settles at safe runtime boundaries; an already-started blocking provider request or tool may finish its call before the next prompt is accepted.

Edit this page on GitHub ↗