magi-code 0.69.0

Repository-aware CLI coding agent for terminal work
Documentation
magi-code-0.69.0 has been yanked.

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

Capability Included behavior More detail
Repository-aware assistant Runs from active working directory, discovers user/repo AGENTS.md, assembles prompt context, and streams provider responses. Instructions, prompts, skills, and primary agents
Multiple interfaces Classic interactive shell, one-shot --print mode, and opt-in Mission Control TUI. Commands and interfaces, Mission Control TUI
Provider support OpenAI Codex OAuth, first-class Anthropic Messages API-key access, and configured OpenAI-compatible custom providers, with provider-authored reasoning summaries where supported and hidden chain-of-thought kept hidden. Provider authentication
Local configuration Defaults to ~/.magi-code; supports MC_HOME for isolated profiles/tests, global non-secret settings.json, and cwd-local .magi-code/settings.json project overrides. openai_codex.fast_mode is the global-only exception to normal project precedence. Configuration
Bounded tools File read/write/search, unified read for local files, internal schemes, and direct URLs, conditional web_extract for static public HTML through a separately installed compatible ax, in-process grep, hashline hash_edit for tag-anchored multi-hunk edits, structural repo_map, guarded shell execution, local image inspection through configured vision models, browser control, web/code search, skill loading, visible tool effects, TTSR streaming reminders, schema-validated subagent output, and safe subagent summaries. Tools and safety model, LSP diagnostics, Security notes
Sessions and context JSONL sessions, structured replay, context budget checks with local BPE token counting, explicit /compact, default-off automatic compaction for persisted primary and child sessions, background session retention cleanup, /prune-sessions, and local cache data. Sessions, context, and cache
Extensibility User/repo skills, prompt fragment overrides, primary-agent profiles, subagent identity profiles, tool-call hooks, and optional tool output compression. Instructions, prompts, skills, and primary agents, Tool-call hooks, Tool output compression, Parallel subagents
Maintainer evals Prompt-fixture dump, tool-choice evals, native skill benches, candidate skill gates, and SkillOpt artifact bridge live in isolated eval harness crate. Eval harness and skill benches, Eval crate README
Maintainer duplicate detection cargo-dupes and jscpd configs detect structural Rust clones and token-level duplicates across source/docs/config. Duplicate detection

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.69.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 provider from interactive shell or environment:

/login
/login openai-codex

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 Activity column is visible by default and can be hidden or shown with Alt-A; 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, /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.

Maintainer/debug prompt fixture dump:

magi-code --dump-prompt --provider anthropic

--dump-prompt exits before authentication and prints provider-ready eval JSON. Eval harness and skill bench docs live in Eval harness and skill benches and evals/magi-code-evals/README.md.

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 openai_codex.fast_mode. 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

Area Dedicated docs
Install/update flow Installation and updates
Commands and interfaces Commands and interfaces
Configuration Configuration
Provider login/logout Provider authentication
Mission Control interface Mission Control TUI
Sessions, context, cache Sessions, context, and cache
Instructions, prompt templates, skills, primary agents Instructions, prompts, skills, and primary agents
Built-in tools and boundaries Tools and safety model
MCP stdio/HTTP tools MCP stdio and HTTP tools
LSP live diagnostics LSP diagnostics
Provider-visible tool summaries Tool output compression
Tool-call hooks Tool-call bash hooks
Subagent delegation Parallel subagents
Common fixes Troubleshooting
Credential and shell safety Security notes
Maintainer eval harness Eval harness and skill benches, Eval crate README
Maintainer duplicate detection Duplicate detection

Feature docs index: docs/features/

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 and must stay private.
  • --color <auto|always|never> controls ANSI color. Precedence: CLI flag > settings.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.
  • openai_responses.text_verbosity optionally selects low, medium, or high for OpenAI Responses requests. Shared value overrides legacy openai_codex.text_verbosity for Codex; legacy setting remains Codex fallback with default low. Custom Responses providers send field only when use_responses_endpoint and supports_text_verbosity are both true; otherwise text stays omitted. Hint affects visible detail, output size, latency, and cost, not reasoning effort, hidden chain-of-thought, tool calls, or hard output-token limits.
  • openai_codex.fast_mode 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.
  • selected_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.
  • 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.
  • 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: openai_codex.fast_mode is global-only and ignores 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.
  • tui.subagent_card_rows controls live subagent card activity rows; it defaults to 5 and accepts 1–50.
  • Automatic compaction is disabled when compaction.auto is absent or enabled is false. To enable it, set 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). With both 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. 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 and is capped. 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.

{
  "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.

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
├── evals/                     # Maintainer eval harness crates and cases
├── 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.

Evaluations

Maintainer evals cover prompt-fixture dumps, tool-choice cases, native skill benches, candidate skill gates, and SkillOpt bridge artifacts. See Eval harness and skill benches and Eval crate README.

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
cargo test --manifest-path evals/magi-code-evals/Cargo.toml --locked

--lib limits execution to unit tests in src; it excludes integration tests, binary tests, and doctests. Cargo filters use substring matching; trailing :: is a module-qualified convenience scope, not ownership-exact. Current cargo test --locked --lib <filter> -- --list counts are: agent:: 338, providers:: 272, tools:: 450, tui:: 956, mcp:: 115, config:: 178, sessions:: 164, and context:: 128. Known cross-domain matches include 3 cli::mcp tests in mcp::, 6 cli::sessions and 52 tui::sessions tests in sessions::, and 23 agent::tests::prompt_context plus 11 tui::state::tests::git_context tests in context::; inspect --list output when exact ownership matters. Counts are test-list evidence, not coverage claims. CI runs root library, binary, foundation, cli_smoke, doctests, and eval tests as serial steps for failure isolation and scoped reruns; partitioning is not claimed to reduce aggregate wall time.

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.