magi-code 0.62.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
• Configuration essentials
• Security essentials
• Repository layout
• Project docs
• Evaluations
• 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 existing-file edits and write for new files.

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

# Claude Code direct HTTP path; reads Claude Code OAuth from Keychain or ~/.claude.
claude auth login
magi-code --provider claude-code --model sonnet --print "Reply with only: ok"

Launch Mission Control TUI:

magi-code --tui

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.

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, /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. 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

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.
• 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 anthropic and direct claude-code providers only. Claude Code sends no cache control when setting absent. Cache writes can increase cost; savings depend on provider cache eligibility, minimum cacheable length, and repeated prompt shape.
• Precedence: CLI flags > environment variables > cwd project settings > global settings/auth > defaults.
• 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.
• 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. The diagnostics tool reads cached file/workspace diagnostics, and references returns bounded path:line:column reference sites for safe paths. See LSP diagnostics.

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.

• Feature documentation
• Eval harness and skill benches
• Eval crate README
• Release checklist and update policy
• PRDs
• ADRs
• RFCs

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:: 246, providers:: 295, tools:: 344, tui:: 777, mcp:: 109, config:: 168, sessions:: 141, and context:: 122. Known cross-domain matches include 3 cli::mcp tests in mcp::, 50 cli/tui tests in sessions::, and 32 agent prompt-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.