Browse documentation

Technical documentation / Reference

Commands and interfaces

Feature docs index · Repository README

Use Mission Control for terminal conversations. The only shipped binary is magi-code; define alias mc='magi-code' if you prefer a shorter command.

Launch options

magi-code                         # open Mission Control
magi-code --no-session            # Mission Control without session persistence
magi-code --continue              # continue the most recent session, or create one if none exists
magi-code --resume <SESSION_ID>   # resume a specific session
magi-code --provider local-provider # override provider
magi-code --model gpt-5.5         # override model
magi-code --version               # print the installed magi-code version and exit
magi-code --update                # update this Cargo installation without starting a session
magi-code --theme <THEME>         # appearance theme for this run
magi-code --prompt "Prompt"       # Mission Control with an initial prompt
magi-code serve --stdio           # local-agent sessions and streamed turns over pipes

Mission Control requires TTY stdin/stdout. --prompt supplies an initial prompt and rejects whitespace-only text. magi-code has no non-interactive conversation mode or positional prompt.

Invalid --resume IDs are usage errors (exit 2). Missing, unreadable, unsafe, or bounded-read sessions fail before provider execution (exit 1) without exposing paths or saved content. --continue resumes the latest eligible session or creates one. Neither attachment flag works with --no-session.

serve --stdio is an explicit Unix-pipe integration endpoint, not a text REPL. Initialization shares Mission Control configuration/discovery and approved MCP startup, without a TTY. It reports local provider readiness and supports owned lazy sessions, exact-ID opening, bounded chat-history pages and full agent turns with streamed text, safe activity, approvals and cancellation. One active run; no queued steering or automatic retry. External settings changes require child restart. See Local-agent protocol for capabilities, effects, bounds and lifecycle.

Mission Control startup queue

During startup, you can edit immediately and queue one prompt. The editor clears for a separate draft; a second submission is rejected. Alt-C cancels the queue but preserves the draft. /help and /quit work immediately; other slash commands wait for readiness. An untouched --prompt follows the same queue and runs once after readiness and the input fence.

Execution waits for settings/policy, selected primary agent, enabled subagent profiles, and all enabled MCP servers. Display metadata does not block it. Critical startup failure restores the terminal, exits nonzero, and does not run the queue. See startup and readiness and cleanup limits for timing, strict MCP startup, and worker bounds.

Run a shell command directly

Submit !command (for example, !git status) with ! as the first character to run guarded bash in the active cwd without a provider request or authentication. Tool restrictions, hooks, and cancellation still apply. Command and output appear locally in Mission Control but not in durable session history.

Add prompt context

Review current changes. #git-status
Map repository layout first. #tree
Address the review notes. #diff-changes

Exact standalone #tree and #git-status expand after Mission Control submission but before request construction and context-budget checks. They run bounded tree and git status commands through guarded bash in the active cwd. Missing commands and other failures become bounded context blocks instead of aborting the prompt. Unknown tags, #40, Markdown headings, and embedded forms such as abc#tree remain ordinary text.

Standalone #diff-changes adds only unresolved line comments through the Diff review backend, without bash or a changed-file scan. Each comment includes ID, path, side, line, original anchor, stale status, and text. Changed code and file lists are excluded. An empty result says No unresolved Diff comments. Only root user prompts and consumed steering expand this tag. Failures report an error; subagent and internal prompts do not expand it. Expanded content enters session history, where later resolution or deletion does not erase it.

Color and exit codes

Color is disabled when saved interface.no_color is true or NO_COLOR is present (even empty). Saved false does not override the environment. Otherwise terminal detection applies. Unicode and animation settings are separate from color. See Runtime theming.

Exit codes: 0 success/help, 1 runtime/provider/tool/general failure, 2 usage/config/launch-validation failure.

Slash commands

CommandUse
/helpOpen Mission Control help, also available with F1.
/updateUpdate with Cargo while idle, then reopen this exact session; see Installation and updates.
/restartRestart the running executable while idle and reopen this exact session without updating; accepts no arguments. See Restart without updating.
/loginOpen Connect Provider.
/login openai-codexStart Codex OAuth or select it in the TUI modal.
/login custom-providerConfigure a label, base URL, and optional API-key environment-variable name, never the key value.
/logoutOpen the logout picker.
/logout openai-codexRemove local Codex auth after confirmation.
/logout anthropicRemove the local provider-keyed auth record after confirmation; cannot unset or override higher-priority ANTHROPIC_API_KEY.
/logout <custom-provider-id>Remove local custom-provider metadata after confirmation.
/newCreate and switch to a new session.
/sideOpen or reopen the independent side conversation; no arguments, unavailable with --no-session. Inside it, /model selects its model, Alt-T cycles its thinking level, and /reset starts fresh.
/compact [custom instructions]Summarize the active persisted session for future requests; retain raw history locally.
/summarize-start, /summarize-stopStart or stop the active session's Summary pane observer; preserves existing entries.
/fast [on|off|status]Toggle Fast with no argument, set it with on/off, or report without writing with status.
/ultrafast [on|off|status]Toggle Ultrafast with no argument, set it with on/off, or report without writing with status. Shares Fast persistence; higher provider usage charges apply.
/changesList sanitized file-tool snapshots by user turn, without file bytes or diffs.
/rewind [--to <turn>] [--mode conversation|files|both] [--dry-run]Rewind before a selected prompt: conversation only (default), files only, or both.
/exportWrite an unencrypted, private local session ZIP. It may contain sensitive data; do not assume it is safe to share.
/prune-sessions [days]Delete sessions strictly older than 30 days by default, or the supplied positive integer. Active sessions stay.
/model <provider>/<model-name>Validate against the cached catalog and save the active session's provider/model preference. Does not change global defaults.
/modelOpen cached model picker, also available with Alt-M while idle. Never refreshes catalogs, even on selection or with missing cache. Use Settings → Choose models → Available models → Refresh catalog to fetch models.
/modelsOpen model availability directly in Settings, in Global scope; enable/disable changes wait for Save.
/settingsEdit grouped Global/Project settings and apply saved changes to future actions.
/usageFetch current Codex quota directly using magi-code's Codex login.
/sessionsOpen the Mission Control session list and preview.
/background-jobsOpen and focus the Background Jobs header panel (Alt-4) listing running background jobs in the primary conversation, including Code Mode. Up/Down selects, k stops the process group, Esc closes when unpinned. Available during active prompts.
/skillsOpen skill availability in Settings; changes wait for Save.
/subagentsEnable/disable discovered subagent profiles immediately.
/mcpToggle configured MCP servers; changes apply on the next launch, not /new.
/system-promptInspect the computed system prompt as read-only source cards, each with its token estimate.
/themeChange appearance; see Runtime theming.
/quitExit.

Slash commands work only in Mission Control. Unknown commands report an error and record a diagnostic when a session is active.

The system-prompt modal preserves prompt order and uses separate cards for system instructions, tools, subagents, skills, injected instruction files, and selected primary persona. Counts use the active model's local estimator and include prompt wrappers; they are not provider billing. Since sections are estimated separately, their counts may not equal the full-prompt total. Scroll with arrows, Page Up/Down, or Home/End. Esc or q closes.

Mission Control provider connection

/login opens the staged Connect Provider modal with current provider status. OAuth stays in the modal; API-key providers show environment setup guidance rather than collecting keys. See Provider connection for keys, cancellation, and replacement confirmation.

Fast mode behavior

/fast and /ultrafast write the non-secret global agent.fast.enabled and agent.fast.ultrafast settings. Modes are mutually exclusive: enabling one selects it; toggling the active mode or using either command's off restores Standard. Toggling the other mode selects it. No command switches models. Invalid arguments print usage: /fast [on|off|status] or usage: /ultrafast [on|off|status]. Each run keeps its starting settings snapshot. Mission Control writes only while idle and off the UI loop; memory changes only after disk success. A pending write blocks another mutation, prompt, or compaction and restores its input. Both commands' status, invalid usage, help, and quit remain available during active work.

Accepted writes settle during cleanup, with no fixed total wait if filesystem work stalls after lock acquisition. Successful writes update the snapshot for later work. See Configuration for eligibility and Fast mode for display and failure handling.

Maintain sessions and restore files

/compact, /export, /changes, /rewind, and /prune-sessions are local maintenance commands, not chat prompts. Only compaction calls a provider; changes and rewind need no provider auth. Mission Control rejects compaction, export, rewind execution, and pruning during active work.

/rewind opens a prompt picker, including prompts without file changes. Up/Down selects; Tab cycles conversation only, files only, and both. Enter confirms; Esc cancels. The picker shows the latest 100 retained prompts. /rewind --to <turn> can select an earlier retained prompt. --mode conversation|files|both preselects a mode. --dry-run never mutates.

The original conversation remains in the session picker until pruned. Selecting it restores conversation, not files. Rewind is not a whole-worktree backup: restoration covers captured write/hash_edit changes, not bash or external edits. Prompts removed from active JSONL by compaction cannot be selected. Retained prompts keep turn numbers and earlier compaction summaries.

Restore verifies hashes before overwriting later user edits. Secret or denied paths, files over the 1 MiB snapshot limit, missing blobs, and hash conflicts are skipped and reported. Created files are removed with containment-safe filesystem operations, not OS trash. Their post-images remain recovery evidence while checkpoint references exist; pruning or storage failure can remove snapshots. A final directory-sync failure after mutation reports a committed-but-undurable warning. Output excludes file bytes, diffs, blob hashes, denied paths, and secret-looking paths.

For retention, export contents, compaction, and permission repair, see Sessions, context, and cache. Deleted sessions cannot be resumed; pruning continues after individual failures and reports deleted, skipped, and failed counts with bounded error categories.

Use Mission Control settings

/settings opens a task-first hub with Search and Browse every setting. Ctrl-G changes Global/Project scope, Ctrl-S saves accepted preferences as one batch, and Tab selects Review/Save/Discard. Availability edits inside Settings share the draft. Dirty close/scope changes offer Save/Discard/Stay. See Edit settings for controls and application timing.

/skills opens the skill availability page in Settings, starting in Global scope. Ctrl-G changes scope; toggles remain drafts until Save, with the same Save/Discard controls as /settings. Standalone /subagents keeps its immediate-save checkbox list: Tab selects Global ($MC_HOME/settings.json, default ~/.magi-code/settings.json) or Project (exact cwd .magi-code/settings.json, no parent search), Enter writes only that scope, and Esc closes. Project disabled lists replace Global lists, including explicit empty lists. Tool availability lives in Settings → Control tools and access.

Model availability lives in Settings → Choose models → Available models. Models default disabled; enable desired models for model pickers. Up/Down and Enter or clicking a model toggles its draft checkbox. Enter or clicking a provider toggles its group; Left folds and Right unfolds. Fold state stays display-only. Refresh catalog preserves drafts. Ctrl-S saves canonical provider/model IDs in providers.catalog.enabled and updates /model. Missing enabled IDs remain visible. Project lists replace Global lists, including explicit empty lists. Disabling the active model never switches it; CLI --model remains an explicit override.

Opening Models uses cached rows and never requests a catalog refresh. At launch, a background worker reloads missing or invalid provider catalogs once; valid catalogs are reused. An empty cache after that attempt shows a manual-refresh hint.

/mcp lists servers from CONFIG_DIR/.mcp.json and cwd/.mcp.json, with stdio/http type, approval status, and a redacted definition pane. Servers default disabled. Up/Down selects, PageUp/PageDown scrolls the definition, Enter approves or revokes the displayed snapshot, and Esc closes. Approval uses a versioned fingerprint in global capabilities.mcp_approvals[canonical_source_path][name]; project settings cannot grant it. Toggles apply next launch, not after /new; live managers do not reconnect.

Disabled definitions undergo structural parsing, but missing environment variables do not block discovery. Enabling expands environment references and validates runtime fields before saving. A stale or failed save refreshes the view without claiming approval succeeded. Definition changes invalidate approval; resolved environment values behind unchanged references do not. See MCP configuration and approval for fingerprint fields and runtime-identity limits.

/usage fetches Codex quota directly from https://chatgpt.com/backend-api/wham/usage off the UI thread using magi-code's stored Codex OAuth login. Each invocation requests fresh data; failures show an error rather than cached quota. It shows percentage-remaining gauges and reset times for the returned usage windows. No external CLI or Claude Code integration is used. Run /login openai-codex if authentication is missing or invalid. Esc/q closes; arrows, PgUp/PgDn, Home, and End scroll. Session-switcher controls are in the TUI guide.

Available tools

See the built-in tool inventory for file tools, shell commands, search, image inspection, subagents, code_mode, and magi_control. Approved MCP servers can add tools.

Edit this page on GitHub ↗