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.99.0+ with Cargo, network access for live provider calls, and a configured provider.
Read reference →Provider authentication
Run /login in Mission Control. Choose OpenAI Codex for ChatGPT OAuth, Claude Subscription for CLI-managed claude.ai access, Anthropic for Messages API access billed through Anthropic API credits, OpenAI for API-key…
Read reference →Claude subscription
Use an installed Claude Code CLI for claude.ai access while magi-code manages tools, approvals, history, and compaction.
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
Protect credentials, review what leaves your machine, and isolate untrusted work. Tool guardrails are not an operating-system sandbox.
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
Settings → Change interface and integrations → Enable diff/changes tab with inline comments for the agent controls the entire feature. It defaults to enabled and applies on save. Global and project scopes are…
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 →Progressive Session Maintenance
Progressive Session Maintenance (PSM) writes background summaries of saved session events. It requires the shared beta flag, is disabled by default, and is separate from the Summary pane.
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
Subagents are optional and disabled by default for both direct calls and Code Mode. Enable them when you want to delegate a specific, independent task. Each child gets its own task and bounded inherited context…
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 →Code Mode
Code Mode runs synchronous JavaScript that calls existing tools and returns selected results. Use it for repeated reads, filtering, comparisons, or edits with mechanical steps. Use direct tools for one-shot work or…
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 →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 →Local clients
Connect a local client
Use magi-code serve --stdio to run an owned local-agent process over Unix pipes. The backend handles models, tools, approvals, and durable history. Your client handles drafts and display.
Read reference →Browse local sessions
Use backend discovery to list saved sessions without reading its storage directly or running a prompt.
Read reference →Select a local-agent model
Model discovery and selection are separate from sending a prompt. The backend supplies available choices and permitted reasoning levels; the client must not infer them from model names.
Read reference →Local-agent stdio protocol
magi-code serve --stdio serves magi-code.local-agent, version 1, on inherited stdin/stdout pipes. No embedding API, daemon, sockets or second binary.
Read reference →Local-agent discovery and catalog extensions
These optional operations extend local-agent stdio, version 1: session.discover, model.catalog.status, model.refresh, and operation.cancel.
Read reference →Display local-agent tool cards
Negotiate tool.cards explicitly to receive structured live and saved tool cards. The backend owns built-in/MCP execution, approvals, cancellation, and history; separately negotiated client-provided tools execute in…
Read reference →Negotiated local-agent tool cards
tool.cards adds structured live and saved cards to existing activities. Clients opt in during initialization. Cards describe observed tool results; they do not change execution, permissions, or approval routing.
Read reference →Client-provided local-agent tools
magi-code serve --stdio can advertise client-provided tools to the existing agent runner. This optional version-1 extension supplements built-ins; it never replaces their execution, permissions or safeguards. The…
Read reference →Tool-card contracts
Shared tool-card projection
src/output/tool_card.rs selects display facts shared by Mission Control and local-agent cards. Inputs include normalized tool detail, observed status, interruption evidence, command text, and selected child facts.…
Read reference →Resource-operation card facts
Read, Grep, AST Grep, Find, and List Files share these display facts across Mission Control and negotiated tool cards. Identify results rows by exact labels, preserve null values, and never parse titles or private…
Read reference →Code Mode and subagent card facts
Mission Control and local-agent cards use the same fact selectors. Local-agent child references use mapped public IDs; Task execution identity is a bounded historical execution label, not a public navigation ID. Use…
Read reference →Web, image, and control card facts
These results rows describe Web, View Image, and Magi Control in schema-1 tool cards. Mission Control, live local-agent cards, and saved cards use the same selection. Identify facts by exact labels, not titles or…
Read reference →Maintainer references
Prompt construction
Magi-code assembles provider instructions from prompt templates, runtime facts, repository instructions, and available skills and agent profiles. Tool definitions travel separately from this text.
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 →Verification
Repository retains only co-located benchmark/profiling workloads and support they use. No unit, integration, doctest or correctness-test suites. Do not add tests or test CI.
Read reference →Profiling benchmarks
Only ignored benchmark/profiling workloads belong in this repository. Keep workloads next to their owning code and retain only support they use. No unit, integration, doctest or correctness-test CI suites.
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 profiling
scripts/profile_cpu.py runs ignored Rust profiling workloads with temporary synthetic settings and local fixtures. It removes credential-looking environment variables from child processes and does not refresh live…
Read reference →Memory profiling
scripts/profile_memory.py measures peak RSS using the ignored CPU profiling workloads. It runs offline with temporary synthetic settings and local fixtures, removes credential-looking environment variables from…
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 →Offline tool-output measurement
Estimate potential tool-result token savings from stored sessions without changing live provider requests.
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.100.0
Published release notes for magi-code 0.100.0.
Read reference →magi-code 0.101.0
Published release notes for magi-code 0.101.0.
Read reference →magi-code 0.101.1
Published release notes for magi-code 0.101.1.
Read reference →magi-code 0.102.0
Published release notes for magi-code 0.102.0.
Read reference →magi-code 0.102.1
Published release notes for magi-code 0.102.1.
Read reference →magi-code 0.102.2
Published release notes for magi-code 0.102.2.
Read reference →magi-code 0.103.0
Published release notes for magi-code 0.103.0.
Read reference →magi-code 0.104.0
Published release notes for magi-code 0.104.0.
Read reference →magi-code 0.105.0
Published release notes for magi-code 0.105.0.
Read reference →magi-code 0.105.1
Published release notes for magi-code 0.105.1.
Read reference →magi-code 0.106.0
Published release notes for magi-code 0.106.0.
Read reference →magi-code 0.106.1
Published release notes for magi-code 0.106.1.
Read reference →magi-code 0.106.2
Published release notes for magi-code 0.106.2.
Read reference →magi-code 0.106.3
Published release notes for magi-code 0.106.3.
Read reference →magi-code 0.107.0
Published release notes for magi-code 0.107.0.
Read reference →magi-code 0.108.0
Published release notes for magi-code 0.108.0.
Read reference →magi-code 0.109.0
Published release notes for magi-code 0.109.0.
Read reference →magi-code 0.109.1
Published release notes for magi-code 0.109.1.
Read reference →magi-code 0.80.0
Published release notes for magi-code 0.80.0.
Read reference →magi-code 0.80.1
Published release notes for magi-code 0.80.1.
Read reference →magi-code 0.80.2
Published release notes for magi-code 0.80.2.
Read reference →magi-code 0.81.0
Published release notes for magi-code 0.81.0.
Read reference →magi-code 0.82.0
Published release notes for magi-code 0.82.0.
Read reference →magi-code 0.82.1
Published release notes for magi-code 0.82.1.
Read reference →magi-code 0.83.0
Published release notes for magi-code 0.83.0.
Read reference →magi-code 0.83.1
Published release notes for magi-code 0.83.1.
Read reference →magi-code 0.83.2
Published release notes for magi-code 0.83.2.
Read reference →magi-code 0.84.0
Published release notes for magi-code 0.84.0.
Read reference →magi-code 0.85.0
Published release notes for magi-code 0.85.0.
Read reference →magi-code 0.86.0
Published release notes for magi-code 0.86.0.
Read reference →magi-code 0.87.0
Published release notes for magi-code 0.87.0.
Read reference →magi-code 0.88.0
Published release notes for magi-code 0.88.0.
Read reference →magi-code 0.89.0
Published release notes for magi-code 0.89.0.
Read reference →magi-code 0.89.1
Published release notes for magi-code 0.89.1.
Read reference →magi-code 0.90.0
Published release notes for magi-code 0.90.0.
Read reference →magi-code 0.90.1
Published release notes for magi-code 0.90.1.
Read reference →magi-code 0.90.2
Published release notes for magi-code 0.90.2.
Read reference →magi-code 0.90.3
Published release notes for magi-code 0.90.3.
Read reference →magi-code 0.90.4
Published release notes for magi-code 0.90.4.
Read reference →magi-code 0.90.5
Published release notes for magi-code 0.90.5.
Read reference →magi-code 0.91.0
Published release notes for magi-code 0.91.0.
Read reference →magi-code 0.95.0
Published release notes for magi-code 0.95.0.
Read reference →magi-code 0.95.1
Published release notes for magi-code 0.95.1.
Read reference →magi-code 0.95.2
Published release notes for magi-code 0.95.2.
Read reference →magi-code 0.95.3
Published release notes for magi-code 0.95.3.
Read reference →magi-code 0.96.0
Published release notes for magi-code 0.96.0.
Read reference →magi-code 0.96.1
Published release notes for magi-code 0.96.1.
Read reference →magi-code 0.96.2
Published release notes for magi-code 0.96.2.
Read reference →magi-code 0.96.3
Published release notes for magi-code 0.96.3.
Read reference →magi-code 0.96.4
Published release notes for magi-code 0.96.4.
Read reference →magi-code 0.96.5
Published release notes for magi-code 0.96.5.
Read reference →magi-code 0.96.6
Published release notes for magi-code 0.96.6.
Read reference →magi-code 0.96.7
Published release notes for magi-code 0.96.7.
Read reference →magi-code 0.97.1
Published release notes for magi-code 0.97.1.
Read reference →magi-code 0.97.2
Published release notes for magi-code 0.97.2.
Read reference →magi-code 0.97.3
Published release notes for magi-code 0.97.3.
Read reference →magi-code 0.97.4
Published release notes for magi-code 0.97.4.
Read reference →magi-code 0.97.5
Published release notes for magi-code 0.97.5.
Read reference →magi-code 0.97.6
Published release notes for magi-code 0.97.6.
Read reference →magi-code 0.98.0
Published release notes for magi-code 0.98.0.
Read reference →magi-code 0.98.1
Published release notes for magi-code 0.98.1.
Read reference →magi-code 0.99.0
Published release notes for magi-code 0.99.0.
Read reference →