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

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.

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

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 writes the non-secret global agent.fast.enabled setting. Invalid arguments print usage: /fast [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. 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.

• Conversation only (default): creates and switches to a new session containing history before the selected prompt. That prompt returns to the editor unsent. The next provider request uses new history; files remain unchanged.
• Files only: restores captured changes from the selected prompt onward. Current conversation and session remain active.
• Both: creates the conversation fork, then restores files. Conflicts can make restoration partial; results appear in the new transcript.

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 six tabs (Context, Agent settings, Models, Tools, Internal Tooling, Other) with local drafts. Tab changes tabs, Ctrl-G switches Global/Project, and Ctrl-S saves after accepting any value edit with Enter. Successful saves reload settings for future actions. See Edit settings for fields, keys, and discard behavior.

/skills, /tools, and /subagents use keyboard-only checkbox lists. 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; Esc closes. Project disabled lists replace global lists, so an empty project list can re-enable globally disabled items.

Model availability lives in /settings → Models. The scrollable list includes enabled and disabled catalog models. Use Up/Down and Enter or click a row to toggle its draft checkbox. Above the list, Refresh catalog accepts a click or Enter when selected; it is unavailable while refreshing. Refresh keeps drafts intact. Ctrl-S stores canonical provider/model IDs in providers.catalog.disabled and updates /model. Disabling the active model does not switch it. CLI --model remains an explicit override.

Opening Models uses cached rows and never requests a catalog refresh; an empty cache shows a manual-refresh hint.

/mcp lists servers from CONFIG_DIR/.mcp.json and cwd/.mcp.json, with stdio/http type and an enabled checkbox. Servers default disabled. Up/Down selects, Enter saves a global capabilities.mcp_approvals[canonical_source_path][name] boolean, and Esc closes. Project settings cannot approve servers. Toggles apply next launch, not after /new; live managers do not reconnect.

Disabled definitions still undergo structural parsing, but missing environment variables do not block discovery. Enabling expands environment references and validates runtime fields before saving; failure leaves approval unchanged. Approval is tied to path/name, not a definition fingerprint, so edits at the same path and name retain approval.

/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

Built-ins include read, write, hash_edit, grep, find, list_files, bash, view_image, subagents, web, and ast_grep. web provides search/open for public research.

Optional LSP diagnostics accompany successful edits. See Tools and safety and LSP diagnostics.

Edit this page on GitHub ↗