Features / practical guide

Build with agents.
Stay in control.

See what magi-code can do, how to use each part, and where to configure it. Start with Mission Control or jump to the feature you need.

Start with Mission Control Browse technical reference

01 / Terminal workspace

Mission Control

Talk with the primary agent, inspect active work, and review changes without leaving your terminal.

Use it

Type a prompt and press Enter. Activity shows tool and subagent work, Summary shows optional progress notes, and Diff shows current worktree changes. Use Alt-1, Alt-2, and Alt-3 to switch views.

Guide active work

Submit another message while work runs to queue guidance. Alt-C recalls queued text or requests cancellation when the queue is empty. Cancellation occurs at safe boundaries.

Add context

Type @ to insert a repository path or $ to select a skill. Prompt tags such as #tree, #git-status, and #diff-changes add common context.

Useful prompt controls

@ inserts a repository path.
$ selects an enabled skill.
! at the start runs a guarded shell command directly.
Ctrl-J inserts a newline; Esc closes the current modal.

Commands you will use often

/help: All commands and keys
/settings: Global and project settings
/new: Start another session
/compact: Shorten active provider context
/quit: Exit Mission Control

Complete command and shortcut reference

02 / Bring your model

Providers and models

Connect Codex, OpenAI, Anthropic, or an OpenAI-compatible provider. Choose models and reasoning settings per session.

Connect

Run /login. Codex uses browser sign-in. OpenAI and Anthropic read API keys from environment variables. Custom providers use a base URL and an optional key environment-variable name.

Choose

Run /model or press Alt-M while idle. If a model is missing, refresh and enable its catalog entry under /settings → Models.

Configure

Adjust available reasoning and response-detail controls near the prompt. Use /fast on to request an eligible provider tier. Access, billing, and speed depend on provider and model.

API-key providers

export OPENAI_API_KEY="your-key"
# or
export ANTHROPIC_API_KEY="your-key"
magi-code

Set keys in the environment before launch. Never put them in settings, prompts, or repository files.

When a model is missing

Open /settings and select Models.
Refresh the catalog.
Enable the model and save with Ctrl-S.
Open /model and select it.

Temporary override: magi-code --provider <id> --model <id>.

Exact authentication, storage, and custom-provider reference

03 / Repository work

Tools and safety

Agents can search code, read and edit files, run non-interactive commands, research public pages, inspect images, and delegate work.

Control tools

Use /tools to enable or disable tools at Global or Project scope. Path settings can permit or deny absolute paths for individual tools.

Inspect activity

Tool cards appear in the transcript. Activity Detail shows status, submitted parameters, and bounded captured output. Start a prompt with ! to run a shell command directly.

Set a safety boundary

Shell guardrails are not an operating-system sandbox. Commands run with your account permissions. Use a container or virtual machine for repositories you do not trust.

Web and images

Public URL opening needs no search key. Search uses Codex OAuth when Codex is active; other providers require EXA_API_KEY. view_image sends an image to your configured vision model. Local terminal previews do not.

Data boundaries

Tool results can enter provider context and saved sessions.
Absolute-path access stays controlled per tool.
Output is bounded, but commands can still change files and processes.
Inspect exports and review-comment expansions before sharing.

Exact tool policies and limits

04 / Keep the thread

Sessions and context

Leave and return to saved conversations, manage long context, and branch from earlier work.

Resume

Use magi-code --continue for the latest session, --resume <SESSION_ID> for a specific one, or /sessions inside Mission Control.

Compact and summarize

/compact summarizes earlier work for future provider requests while local history remains. Summary view can make separate provider calls for short progress entries.

Rewind and export

/rewind branches from an earlier prompt and may restore captured file-tool changes. It cannot undo every shell or external side effect. /export creates an unencrypted session ZIP.

Launch choices

--continue: Most recent session
--resume ID: Named saved session
--no-session: No resumable history
/prune-sessions 7: Delete sessions older than seven days

Know what persists

Session history is local durable data. Compaction changes future provider context, not saved history. Rewind forks instead of truncating the original. Exports may include prompts, responses, tool data, paths, and source content.

Retention, checkpoint, and storage details

05 / Inspect changes

Review and history

Read current worktree diffs, attach local comments to lines, and send unresolved feedback back to the agent.

Review a diff

Open Diff or press Alt-3. Choose a file, move through original and changed lines, then press Enter to add a comment. Press F5 after files change.

Send feedback

Saved comments remain local until your prompt includes #diff-changes. Only unresolved comments and their line context are added, not the complete diff.

Reuse prompts

Mission Control suggests previous single-line prompts from the same repository. Press Right Arrow to accept. Launch with MC_PROMPT_HISTORY=0 to disable suggestions.

Comment controls

Alt-S: Save
Alt-R: Resolve or reopen
Alt-D: Delete
Esc: Cancel before save starts

Comment lifecycle

Comments belong to the worktree, not one session. A comment becomes stale when its original line is missing or ambiguous. Delete and recreate it to establish a new anchor. Sending a comment copies it into session and provider history.

Comment storage, reanchoring, and limits

06 / Shape behavior

Agent customization

Give agents standing repository rules, reusable specialist guidance, and selectable profiles.

Instructions

Place AGENTS.md at your launch directory for repository rules. User-level rules live at ~/.magi-code/AGENTS.md. Instructions are sent to providers, so keep secrets out.

Skills

Put project skills under .agents/skills/<name>/SKILL.md or user skills under ~/.magi-code/skills/. Use /skills to manage them and $ to select one in a prompt.

Profiles

Primary-agent profiles under ~/.magi-code/agents/ can select a model, reasoning level, disabled tools, and output rules. Profiles shape behavior but cannot grant extra permissions.

Repository instruction example

# Repository instructions

- Run cargo fmt --check after Rust edits.
- Preserve public behavior.
- Do not edit generated files.

Optional subdirectory discovery can load more specific AGENTS.md files when tools enter those paths.

Choose the right layer

Instructions: standing repository rules.
Skills: reusable guidance loaded when relevant.
Profiles: selectable persona, model, reasoning, and restrictions.
Prompt overrides: advanced replacement of product defaults.

Discovery, precedence, and profile fields

07 / More than one thread

Side agents and parallel work

Open a separate conversation or ask the primary agent to delegate independent tasks.

Side conversation

Run /side in a saved session. It has separate context, usage, cancellation, and transcript. Configure its provider and model under Agent settings.

Parallel subagents

Ask the agent to investigate independent tasks in parallel. A batch supports up to ten tasks with up to four running at once. Use inspect mode when tool-level read-only work matters.

Avoid collisions

Primary, side, and delegated agents share the same repository by default. They are not isolated worktrees. Avoid assigning overlapping edits.

Delegation prompt

Investigate these independently with subagents:
authentication flow, session storage, and updates.
Combine findings without editing files.

Say to use subagent inspect mode when read-only enforcement matters.

Profiles and cost

Subagent profiles live under ~/.magi-code/subagents/ and are managed with /subagents. They can narrow tools, select models, and require structured output. Every child request uses provider quota.

Subagent lifecycle, profiles, retries, and limits

08 / Extend the harness

Integrations and automation

Add external tools, post-edit diagnostics, trusted local automation, and optional semantic checks.

MCP

Define stdio or Streamable HTTP servers in .mcp.json, approve them with /mcp, then restart. Definitions never approve themselves.

LSP

Enable LSP diagnostics in settings to append fresh errors and warnings after edits to supported Rust, TypeScript, JavaScript, Python, or Go files.

Hooks

Run trusted local scripts before or after tools and messages. Hooks use your local permissions and may receive sensitive tool data.

Jev

Set TYPESAFE_API_KEY, then enable Jev and selected checks under Internal Tooling. Enabled checks send bounded assessment state to TypeSafe.

MCP setup

{
  "mcpServers": {
    "example": {
      "command": "example-mcp-server",
      "args": ["--stdio"]
    }
  }
}

Save globally at ~/.magi-code/.mcp.json or locally at .mcp.json. Test with magi-code mcp test example.

LSP setup

{
  "capabilities": { "lsp": {
    "enabled": true,
    "inject_diagnostics_on_edit": true
  }}
}

Install the language server separately. Diagnostics supplement tests and builds; they do not replace them.

MCP server configuration and contracts

09 / Make it yours

Appearance and terminal features

Choose a theme, reduce motion, set panel defaults, and preview local images in supported terminals.

Themes

Run /theme to preview and save a theme, or launch with --theme for a temporary choice. Custom themes live under $MC_HOME/themes/.

Motion and layout

Set interface.appearance.reduced_motion in Global or Project settings. Set Show panel on startup for future launches; Alt-A toggles it during a run.

Local images

Kitty and Ghostty can show local image previews in the transcript without calling a provider. Agent image inspection is separate and uses the configured vision model.

Appearance settings

{
  "interface": {
    "appearance": {
      "theme": "matrix-green",
      "reduced_motion": true
    },
    "no_color": false
  }
}

Terminal behavior

NO_COLOR disables color regardless of saved settings. Image previews accept local PNG, JPEG, GIF, and WebP files, stay in the main transcript, and fall back to text in unsupported terminals.

Custom theme tokens and complete example

10 / Set your defaults

Configuration

Use the interface for common options, JSON for advanced settings, and launch flags for one-off overrides.

Global

Applies everywhere. Stored at ~/.magi-code/settings.json, or $MC_HOME/settings.json when MC_HOME is set.

Project

Applies only to the exact launch directory. Stored at .magi-code/settings.json. Project values override matching global values; parent directories are not searched.

Temporary

Flags such as --provider, --model, and --theme override saved choices for the current process.

Edit settings in Mission Control

Run /settings.
Use Tab between categories.
Use Ctrl-G to change Global or Project scope.
Edit with Enter.
Save and reload with Ctrl-S.

Minimal settings file

{
  "$schema": "./state/settings.schema.json",
  "schema_version": 2,
  "agent": { "fast": { "enabled": false } }
}

Never store API keys, OAuth tokens, bearer headers, or account IDs here.

Every setting, merge rule, and environment override

11 / Common fixes

Troubleshooting

Resolve common install, authentication, session, skill, diagnostic, and integration problems.

magi-code: command not found

Add Cargo's binary directory to PATH: export PATH="$HOME/.cargo/bin:$PATH". Install Rust from rustup if cargo is also missing.

Provider login or model selection fails

For Codex, rerun /login openai-codex. For OpenAI or Anthropic, set the required API-key environment variable before launch. Then refresh Models in /settings. Launch flags override project settings, which override global settings.

A session does not resume

Use /sessions to confirm it exists and copy its exact ID. On Unix, inspect permission repairs with magi-code sessions repair-permissions --dry-run before applying them.

Instructions or skills are missing

Launch from the directory containing AGENTS.md. Confirm skills use <skill-name>/SKILL.md under a supported root, check /skills, and save settings with Ctrl-S.

LSP diagnostics do not appear

Enable LSP, install the language server on PATH, and remember that only supported files changed through editing tools trigger injected diagnostics. Run normal project checks when diagnostics are absent.

An MCP server is unavailable

Run magi-code mcp list and magi-code mcp test <server>. Confirm its file is global or in the exact launch directory, approve with /mcp, then restart.

Exact errors and recovery behavior

Ready to work

Open a repository.
Start a session.

cargo install magi-code --locked
cd /path/to/your/repository
magi-code

Then run /login in Mission Control.

Build with agents.Stay in control.