Technical documentation
Exact behavior.
One searchable reference.
Settings, limits, storage, integration contracts, security boundaries, and implementation details for magi-code.
Getting started
Installation and updates
You need Rust 1.88.0+ with Cargo, network access for live provider calls, and a configured provider. Built-in content search does not require ripgrep; ffgrep remains an alias for grep.
Read reference →Provider authentication
Run /login in Mission Control. Choose OpenAI Codex for ChatGPT OAuth, OpenAI for API-key access, Anthropic for Messages API access billed through Anthropic API credits, or Custom Provider for an OpenAI-compatible…
Read reference →Configuration
Runtime state defaults to /.magi-code. Set an absolute MC_HOME for a separate profile or test run:
Read reference →Troubleshooting
Paths below use /.magi-code unless MC_HOME is set. Errors report the resolved paths.
Read reference →Security notes
Codex refreshes OAuth before applicable use, performs network exchange outside auth locks, and rejects stale/competing refresh writes. Provider generations survive logout. See Provider authentication.
Read reference →Mission Control
Commands and interfaces
Use Mission Control for terminal conversations. The only shipped binary is magi-code; define alias mc='magi-code' if you prefer a shorter command.
Read reference →Mission Control TUI
Use Mission Control to edit prompts, follow tools and subagents, inspect captured output, and change settings without leaving the terminal.
Read reference →Prompt-history suggestions
Mission Control shows a dim completion of previously submitted prompts. Matching is an exact, case-sensitive prefix; frequently used prompts rank first, then recently used prompts.
Read reference →Diff review
Click Diff on Mission Control's right rail. Diff replaces the conversation body while keeping the prompt and rail. The three columns use 20% for folders, files and comments, 40% for Original, and 40% for Diff.…
Read reference →Runtime theming
Magi-code uses one Opaline semantic theme for Mission Control. Machine output, protocol output, sessions, provider requests, and tool payloads remain unstyled.
Read reference →Local transcript images
Mission Control shows actual Kitty graphics below the text of view_image cards and completed assistant Markdown containing description. Previews are limited to the main transcript; activity details, subagent viewers…
Read reference →Sessions and agents
Sessions, context, and cache
Resume work, shorten provider context without losing local history, export a session, or remove old sessions. Paths use /.magi-code by default; MC_HOME relocates that directory.
Read reference →Session summarizer
Mission Control can turn recent session activity into short progress entries in the Summary pane. It is disabled by default.
Read reference →Side agent
Submit /side with no arguments in Mission Control after startup. It opens one independent conversation in a modal, including while the primary agent is running. /side is unavailable with --no-session.
Read reference →Instructions, prompts, skills, and primary agents
Use AGENTS.md for shared rules, prompt fragments for assistant guidance, primary-agent profiles for a persona, and skills for instructions loaded on demand. Paths below use the default /.magi-code; setting MC_HOME…
Read reference →Parallel subagents
Ask the assistant to delegate independent tasks with the subagents tool. Each child gets its own task and bounded inherited context; optional identity profiles supply a persona, model, tool restrictions, or output…
Read reference →Tools and integrations
Tools and safety model
Choose a tool below, then check its path, output, and credential limits before use. Shell guardrails are not an OS sandbox.
Read reference →MCP stdio and HTTP tools
Configure Model Context Protocol (MCP) servers so their tools appear beside magi-code's built-ins. You can diagnose setup without provider credentials.
Read reference →LSP diagnostics
LSP diagnostics are an opt-in live feedback loop for coding sessions. After successful write or hash_edit, magi-code can sync the changed file to a language server, wait briefly for fresh diagnostics, and append a…
Read reference →Tool-call bash hooks
Trusted local hooks can audit, enforce policy, send notifications, or inject context. They are disabled by default and run in the active agent cwd, including child cwd for inherited subagent hooks.
Read reference →Jev and internal tooling
magi-code uses TypeSafe Jev for bounded semantic judgments. Jev receives state plus a typed question and returns structured probabilities. It does not replace the main conversation model.
Read reference →Offline tool-output measurement
Estimate potential tool-result token savings from stored sessions without changing live provider requests.
Read reference →Maintainer references
Prompt construction
Explain how magi-code builds provider-visible prompt context: static templates, runtime facts, AGENTS.md files, tools, skills, subagents, provider request mapping, and customization points.
Read reference →Session replay reuse
Prompt projection and agent execution share one bounded replay cache per AgentSession. The cache stores normalized replay output, diagnostics, a content fingerprint, the session path and file identity, and the…
Read reference →Risk-based testing
Tests protect contracts and risks, not raw counts. P0 blocks release; P1 protects important behavior; P2 samples boundaries and failure modes.
Read reference →Duplicate detection
cargo-dupes and jscpd are maintainer checks for duplicate code. They overlap but detect different kinds of duplication.
Read reference →Prompt-cache audit scripts
Maintainer scripts under scripts/ check prompt-cache readiness without changing provider runtime code. The static audit is offline by default. The live checker requires explicit opt-in for networked cold/warm…
Read reference →CPU Hotspot Profiling Workflow
Maintainer workflow for issue #48 / PRD-0056. Default path is credential-free and offline: scripts/profile_cpu.py runs ignored Rust harness tests with a temporary synthetic MC_HOME, no auth.json, credential-looking…
Read reference →Memory Usage Profiling Workflow
Maintainer workflow for credential-free peak RSS checks. Default path is offline: scripts/profile_memory.py runs the same ignored Rust profiling harness tests as CPU profiling with a temporary synthetic MC_HOME, no…
Read reference →Repeated setup benchmark
Credential-free benchmark for startup settings work, repeated classic-prompt setup, ten identical provider overrides, and provider tool-body construction.
Read reference →Official release notes
On the first eligible Mission Control launch after an update, official notes appear below the rabbit. If you skipped releases, available approved notes appear oldest first, with a version heading for each release.
Read reference →Versioned release notes
magi-code 0.80.0
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.80.1
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.80.2
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.81.0
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.82.0
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.82.1
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.83.0
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.83.1
Close Mission Control dialogs with the mouse as well as the keyboard.
Read reference →magi-code 0.83.2
Technical behavior, configuration, limits, and implementation details.
Read reference →magi-code 0.84.0
Agents can now compact long conversations and continue automatically through magi_control.
Read reference →magi-code 0.85.0
Jev can now review comments and documentation before write and hash_edit changes run. Rejected prose includes guidance to load $writer-humanizer, revise, and retry.
Read reference →magi-code 0.86.0
Agents can use Jev for bounded Choice, Score, and Noul judgments.
Read reference →