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.
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. Shift-Tab switches between Transcript and Changes. Header toggles Alt-1, Alt-2, and Alt-3 open Activity Tree, Session Files, and Summary; Alt-A pins them beside Transcript.
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.- Alt-V pastes a clipboard image, otherwise text.
- 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
/background-jobs- List or stop background jobs
/quit- Exit Mission Control
02 / Bring your model
Providers and models
Connect Codex, a Claude subscription, OpenAI, Anthropic, or an OpenAI-compatible provider. Choose models and reasoning settings per session.
Connect
Run /login. Codex uses browser sign-in. Claude Subscription uses your installed Claude Code CLI and its claude.ai 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 or /ultrafast on to request an eligible Codex tier; Ultrafast carries higher usage charges. 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-codeSet keys in the environment before launch. Never put them in settings, prompts, or repository files.
Claude subscription
claude auth login
magi-code --provider claude-subscription --model claude-opus-5-5Uses Claude Code's claude.ai sign-in; magi-code never stores those credentials. API-key and alternate-backend overrides are removed from its Claude child processes. Requires macOS, Linux, or WSL.
When a model is missing
- Open
/settingsand select Models. - Refresh the catalog.
- Enable the model and save with Ctrl-S.
- Open
/modeland select it.
Temporary override: magi-code --provider <id> --model <id>.
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 /settings → 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, each with the agent's stated intent. Activity Detail shows status, submitted parameters, and bounded captured output. Start a prompt with ! to run a shell command directly.
Batch with Code Mode
Enabled by default unless explicitly disabled in settings. Enable or disable it under /settings → Tools → Code Mode, save, then restart. The agent can run short JavaScript batches of tool calls with the same approvals, hooks, and records. Completed actions stay applied after a later failure.
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.
Background jobs
Agents can start dev servers, watchers, and long builds with bash background: true, up to four running per session. Run /background-jobs to list them; ↑ / ↓ selects and k stops a job's process group.
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.
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. Optional Progressive Session Maintenance (/settings → PSM) writes background event summaries with extra provider calls.
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.
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
Click Changes on the right rail or press Shift-Tab from Transcript. 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.
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.
07 / More than one thread
Optional side conversations and subagents
Keep the main task in one conversation. Open a side conversation or opt in to subagents when you want to assign independent work.
Side conversation
Run /side in a saved session. It has separate context, usage, cancellation, and transcript. Configure its provider and model under Agent settings.
Opt-in subagents
Subagents are off by default for direct calls and Code Mode. Enable subagents in the relevant tool picker under /settings → Tools, save, and restart. Then ask for specific independent tasks. 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.
After enabling subagents
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.
08 / Extend the harness
Integrations and automation
Add external tools, 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; changing one requires approval renewal.
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 Optional Features. Optional Bash file tracking adds inferred file activity to Session Files. 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.
Build your own client: magi-code serve --stdio runs the same agent over a local pipe. See the local-agent protocol
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 settings. Open panels, their order, and pin state save automatically and return on restart.
Local images
Kitty, Ghostty, and Herdr 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.
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. Tabs: Agent settings, Knowledge, Models, Tools, Optional Features, TUI, PSM. - Use Tab between tabs.
- Use Ctrl-G to change Global or Project scope.
- Expand a category with Enter or Space, then edit with Enter.
- Save with Ctrl-S.
Some settings are global-only. Code Mode and MCP changes require restart; see the configuration reference for each setting.
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.
11 / Common fixes
Troubleshooting
Resolve common install, authentication, session, skill, 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 Claude Subscription, run claude auth login. Magi-code removes API-key overrides from its Claude child; the parent environment stays unchanged. For OpenAI or Anthropic, set the required API-key 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.
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. An edited definition invalidates its approval until you renew it in /mcp.
Ready to work
Open a repository.
Start a session.
cargo install magi-code --locked
cd /path/to/your/repository
magi-codeThen run /login in Mission Control.