magi-code 0.74.0

TL;DR: install published versions with Cargo, run magi-code, use /login to connect provider, then launch from repository you want agent to work in.

Table of contents

• What it does
• Quick start
• Feature documentation
• Runtime theming
• Configuration essentials
• Security essentials
• Repository layout
• Project docs
• License

What it does

The crate builds one command-line binary: magi-code. If you prefer shorter command, define shell alias such as alias mc='magi-code'; this repository does not ship mc binary target.

File read defaults local files to hashline mode: [path#TAG] header plus LINE:TEXT anchors for hash_edit. Use selectors such as :raw, :50-100, or :raw:50-100 for plain text and line windows. read also accepts skill://<name>, skill://<name>/<relative-reference>, session://, issue://, pr://, and direct http/https targets through bounded internal readers. hash_edit uses latest current-session tag; after edit or stale-tag failure, use fresh response tag or re-read before more edits. Use hash_edit for anchored changes to existing files and write for new files or complete replacements.

For direct public URLs, use read for public unauthenticated plain text, Markdown, or JSON ordinary GETs; use conditional web_extract for static HTML outline/locate/CSS text/attribute/count/rows/table extraction; use browser for JavaScript, interaction, cookies, auth/session state, visuals, or screenshots; and use bash for custom methods, headers, bodies, redirect control, binary downloads, private/local services, or an explicit request. web_extract appears only when compatibility probes accept a compatible external ax for the current provider-run invocation and the tool is enabled. Detection runs once per provider-run invocation and caches the resolved path and version for that invocation and inherited subagents; it does not copy, hash, or cryptographically pin the binary. See Configuration for setup. Magi-code never installs ax or rewrites curl. Official ax install guidance is separate from magi-code.

Quick start

Requirements: Rust 1.88.0+ with Cargo, provider network access, and credentials for openai-codex, anthropic, or configured custom provider. Content search runs in-process; external ripgrep is not required.

Install from crates.io:

cargo install magi-code --locked

For this release, install exact version with:

cargo install magi-code --version 0.74.0 --locked

Install from this source checkout:

cargo install --path . --locked

Generic command above installs latest published version. Use exact X.Y.Z only when intentionally selecting known published version.

Run from target repository:

magi-code
magi-code --version

Connect a provider from the interactive shell or Mission Control:

/login
/login openai-codex

In Mission Control, /login opens one staged Connect Provider modal. It shows each provider's current status; API-key setup uses environment guidance, and custom-provider and OAuth flows never ask for an API-key value. See Provider authentication for details.

ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>" magi-code --provider anthropic --model claude-sonnet-4-5-20250929 --print "Reply with only: ok"

Launch Mission Control TUI:

magi-code --tui
magi-code --tui --prompt "Summarize this repository."

CLI setup still loads settings/config, instructions, skills, and session setup/discovery before TUI entry. It schedules automatic session pruning before TUI entry on an unjoined background thread; pruning may overlap interactive startup and is not readiness-critical. Once Mission Control's interactive runtime starts, it paints an interactive first frame while execution readiness loads. The accepted controlled TestBackend responsiveness gate is strict <50 ms> from process-side edit receipt through bounded post-drain/state projection to completed Ratatui draw; <16 ms> remains a non-gating, unverified physical-terminal target, and no physical TTY test has been performed. An untouched --prompt follows the one-item startup queue and runs once after readiness and the input fence; editing, queue controls, and failure behavior are documented in Mission Control TUI. See Commands and interfaces for launch constraints.

The right column is visible by default, with a vertical Activity/Summary rail at the far right when space permits. Alt-1 selects Activity and Alt-2 selects Summary. In normal use, Tab cycles focus through Prompt, Transcript, and the selected tab's primary pane (Activity Tree or Summary). Alt-A hides or shows the entire right column, including the rail; the choice is display-only and not persisted. See Mission Control TUI for the full controls table.

Run one prompt for scripts/logs:

magi-code --print "Summarize this repository."

Add bounded local context to prompts:

Review current changes. #git-status
Map repository layout first. #tree

#git-status and #tree work in --print, classic shell, and Mission Control. Commands run from active cwd through guarded bash; failures become bounded context blocks instead of aborting prompt.

Mission Control exposes sanitized full local tool details in Selected Activity Detail; see Mission Control TUI for the display and hydration boundaries.

Update installed binary by reinstalling desired crates.io version:

cargo install magi-code --version X.Y.Z --locked --force

Common slash commands: /help, /login, /logout, /setmodel, /models, /usage, /new, /changes, /rewind [--to <turn>] [--dry-run], /compact, /fast [on|off|status], /theme, /prune-sessions, /export, /sessions, /skills, /tools, /subagents, /mcp, /system-prompt, /quit. Full flags, slash-command behavior, Mission Control modal keys, and prompt tags live in Commands and interfaces.

Repair broad legacy session permissions without shell commands:

magi-code sessions repair-permissions --dry-run
magi-code sessions repair-permissions

Use --yes for automation. Command resolves MC_HOME, changes only validated legacy session objects, and fails closed on unsafe layouts.

User customization/auth files live under MC_HOME when set, otherwise ~/.magi-code; project-scoped settings can live at <cwd>/.magi-code/settings.json and override global settings for that cwd only, except for global-only agent.fast and interface.appearance. Full configuration and customization rules live in Configuration and Instructions, prompts, skills, and primary agents.

Provider-visible local prompt sources use bounded byte reads with per-file and startup aggregate limits; profile and skill symlinks are rejected. Details: Instructions, prompts, skills, and primary agents.

See Installation and updates for crates.io installs, manual versioned updates, source-checkout installs, and aliases.

Feature documentation

Configuration essentials

• Runtime state defaults to ~/.magi-code; set MC_HOME to isolate runs, profiles, or tests. Diagnostics name resolved MC_HOME paths.
• Project overrides live only at exact cwd <cwd>/.magi-code/settings.json; no parent-directory search.
• settings.json is non-secret; auth.json stores provider credentials plus non-secret internal refresh metadata and must stay private/owner-only on Unix. Users must not edit the metadata.
• --color <auto|always|never> controls ANSI color. Precedence: CLI flag > interface.no_color > NO_COLOR > auto TTY detection. NO_COLOR disables ANSI color only; Unicode marks and line editor remain TTY-gated.
• Exit codes: 0 success/help, 1 runtime/provider/tool/general failure, 2 usage/config/launch-validation failure.
• providers.openai_responses.text_verbosity optionally selects low, medium, or high for OpenAI Responses requests. Codex uses the shared value first and otherwise falls back to legacy providers.openai_codex.text_verbosity; custom Responses providers send text.verbosity only when the shared value and both use_responses_endpoint and supports_text_verbosity settings are enabled. With no applicable value, the field stays omitted. The hint affects visible detail, output size, latency, and cost, not reasoning effort, hidden chain-of-thought, tool calls, or hard output-token limits.
• agent.fast.enabled is a non-secret, global-only boolean (default false). /fast toggles it in global settings and preserves unrelated and unknown settings fields. Project settings cannot override it. When enabled, a catalog entry with explicit service-tier metadata that does not include Fast remains Standard; only missing tier metadata or a missing catalog model entry permits the strict fallback for a normalized Codex GPT model at version 5.4 or later. The provider controls Fast entitlement, actual speed, and credit/billing behavior. Mission Control blocks retry after an unacknowledged Fast persistence-worker failure with no event and requires a restart; a delivered failure is cleared when its matching event is handled.
• Fast applies to eligible primary turns, subagents, and manual or automatic blocking compaction; session-title requests are excluded. Custom providers opt in only through nested providers.custom.<id>.fast_mode with an exact model id or the sole "*" entry; capability is never inferred.
• agent.model.thinking_level persists universal values (default, low, medium, high, xhigh, max). Explicit provider catalog efforts win; built-in profiles protect known model families from generic catalog booleans; boolean reasoning metadata only enables generic effort levels for otherwise unknown models. Anthropic high/max maps to Messages API thinking budgets; default omits thinking.
• providers.anthropic.cache_ttl is optional in settings.json; accepted values are "5m" and "1h". It enables Anthropic prompt-cache request fields for the anthropic provider. Cache writes can increase cost; savings depend on provider cache eligibility, minimum cacheable length, and repeated prompt shape.
• Settings mutations preserve unknown top-level fields and existing unknown fields in supported nested settings objects when those fields are not changed. Malformed or unsupported settings are not rewritten. See Configuration for the preservation and validation rules.
• sessions.retention_days controls background cleanup; manual /prune-sessions [days] remains available. See Sessions, context, and cache for retention behavior.
• Precedence: CLI flags > environment variables > cwd project settings > global settings/auth > defaults. Exception: agent.fast and interface.appearance are global-only and ignore cwd project values.
• Configuration docs cover schema, paths, project/global merge behavior, subdirectory AGENTS.md discovery, MCP servers, custom providers, view_image, hooks, tool settings, and environment variables: Configuration.
• interface.tui.subagent_card_rows controls live subagent card activity rows; it defaults to 5 and accepts 1–50.
• Automatic compaction is disabled when agent.compaction.auto is absent or enabled is false. To enable it, set agent.compaction.auto.enabled: true plus one or both triggers: threshold_percent (1–100, projected next-request tokens as a percentage of active model maximum) and/or threshold_tokens (positive fixed count). max_compactions_per_run is optional: omission defaults to 4, 0 removes only the per-run compaction-count cap (existing provider, tool, context, and cancellation bounds still apply), and 1–255 set a finite per-run cap. With both triggers set, whichever condition is reached first triggers; the continuation policy uses the lower effective token cutoff. At or above the selected trigger, eligible persisted primary and child sessions compact at clean completed-turn or settled tool-continuation boundaries before another provider request. If submitted input would push the full request above hard usable context budget, eligible runs compact before recording or sending input, then send original input once; that preflight compaction counts toward a configured finite cap. Pending steering replaces post-turn fallback; otherwise runtime persists and submits literal lowercase continue with origin: "automatic_compaction", while UI labels the prompt automatic. Repeated same-run compaction requires new provider-visible growth. It stops at the configured finite per-run cap; setting 0 removes only that cap, not existing provider, tool, context, or cancellation bounds. See Sessions, context, and cache.
• Custom providers support optional reasoning_protocol: gpt-like (default) or anthropic-like request fields on existing OpenAI-compatible endpoints; it does not enable Anthropic Messages transport. gpt-like controls request dialect only. Exact non-empty catalog reasoning_efforts metadata determines levels; otherwise supports_reasoning: true enables default|low|medium|high, while missing or false metadata exposes only default. Unsupported persisted levels clamp non-destructively to default.

Optional LSP diagnostics are disabled by default. Enable them only when matching language servers are installed on PATH; LSP adds a fast edit feedback loop but does not replace cargo check, tests, or project-specific verification.

{
  "capabilities": {
    "lsp": {
      "enabled": true,
      "inject_diagnostics_on_edit": true,
      "diagnostics_wait_ms": 2000,
      "idle_shutdown_minutes": 10,
      "servers": {
        "rust-analyzer": { "command": "rust-analyzer", "args": [] },
        "typescript-language-server": { "command": "typescript-language-server", "args": ["--stdio"] }
      }
    }
  }
}

When enabled, successful write/hash_edit calls can append a redacted DIAGNOSTICS block capped at 20 diagnostics and about 2 KiB. Missing, slow, crashed, or indexing servers degrade silently for edit injection; edits still succeed or fail only by normal file-tool rules. See LSP diagnostics for edit-injection behavior.

Security essentials

• Provider credentials are assistant transport credentials only; Cargo installation uses Cargo's own authentication and is not performed by magi-code.
• bash / shell has guardrails but no OS-level isolation; sandbox hostile repositories separately.
• settings.json is non-secret. Use environment references for sensitive MCP HTTP headers; keep OAuth tokens under $MC_HOME/mcp-tokens/<server>.json.
• Search tools require EXA_API_KEY from process environment only.
• On Unix, ambient bash / shell commands use /bin/bash -lc; native Windows uses PowerShell (pwsh, then powershell.exe) with -NoProfile -NonInteractive -Command. Hooks use the platform's sanitized shell: /bin/bash --noprofile --norc -c on Unix and PowerShell with -NoProfile -NonInteractive -Command on Windows, with deny-by-default subprocess environment profiles; ambient shell commands have no OS-level sandbox. See Security notes for the profile details.
• MCP server/tool names use the exact mcp__<server>__<tool> form. Both components must be non-empty and use only ASCII letters, digits, _, or -; neither may contain __. Server ids cannot end with _, but tool names may; qualified names are limited to 64 UTF-8 bytes total. See MCP stdio and HTTP tools.
• Codex refreshes OAuth credentials before applicable use, keeps network exchange outside auth locks, and rejects stale or competing refresh writes; provider generations survive logout. See Provider authentication.

See Security notes and Tools and safety model for full boundaries.

If normal startup reports broad session permissions, run magi-code sessions repair-permissions --dry-run, then use interactive mode or --yes. Command resolves MC_HOME, repairs only validated legacy objects, never follows links or recurses, and fails closed on unsafe layouts. See sessions, context, and cache and troubleshooting.

Repository layout

.
├── README.md                  # Project overview and feature-doc entrypoint
├── Cargo.toml                 # Rust 2024 crate; lib `magi_code`, bin `magi-code`
├── Cargo.lock                 # Locked dependency graph
├── config/                    # Example non-secret settings
├── docs/                      # Feature docs, PRDs, ADRs, RFCs, release notes
├── prompts/                   # Bundled runtime prompt fragments
├── scripts/                   # Maintainer audit/profiling/live-check helpers
├── src/                       # CLI, provider, tool, session, skill, subagent, TUI code
└── tests/                     # Integration regressions

Project docs

Public Rust API compatibility is guarded in CI with cargo semver-checks on pull requests against base branch. New public exports should be intentional and covered by tests/foundation.rs or equivalent external-use evidence.

• Feature documentation
• Release checklist and update policy
• PRDs
• ADRs
• RFCs

Maintainer test commands

Use narrow convenience scopes while changing one ownership domain, then run full checks before merge:

cargo test --locked --lib agent::
cargo test --locked --lib providers::
cargo test --locked --lib tools::
cargo test --locked --lib tui::
cargo test --locked --lib mcp::
cargo test --locked --lib config::
cargo test --locked --lib sessions::
cargo test --locked --lib context::
cargo test --locked --bin magi-code
cargo test --locked --test foundation
cargo test --locked --test cli_smoke
cargo test --locked --doc

The maintainer commands above provide focused checks; run cargo test --locked --quiet for the full suite. CI runs each root partition in a named, failure-isolated step, records status and duration telemetry, uploads the combined report even when tests fail, and gates clippy on all partition outcomes. See Risk-based testing.

This project uses Apache License 2.0 with Commons Clause. It is source-available and not an OSI-approved open-source license or plain Apache-2.0. Apache permissions allow modification, derivative works, free redistribution, and free sublicensing when attribution, license, modification, and Commons Clause notices are retained; internal commercial use remains allowed. Commons Clause prohibits selling magi-code itself or offering a paid product or service whose value derives entirely or substantially from magi-code functionality. See LICENSE.