Installation and updates
Getting started · Technical reference index · Repository README
Install and start
You need Rust 1.99.0+ with Cargo, network access for live provider calls, and a configured provider.
rustc --version
cargo --version
cargo install magi-code --locked
This installs the latest published release.
Make sure Cargo's bin directory is on PATH, then launch from the repository you want to work in:
export PATH="$HOME/.cargo/bin:$PATH"
cd /path/to/your/repository
magi-code
Connect a provider in Mission Control:
/login
/login openai-codex
Use ChatGPT/Codex OAuth, a claude.ai subscription through installed Claude Code, an Anthropic API key, or a configured OpenAI-compatible provider. Claude subscription needs no separate SDK package. See Provider authentication.
Mission Control starts by default and requires TTY stdin/stdout. To queue its first prompt:
magi-code --prompt "Summarize this repository."
For integrations without a terminal, use serve --stdio. There is no one-shot text mode or positional prompt.
Update with Cargo
Mission Control checks crates.io after opening and every four hours while running. A newer stable release produces a notice and an /update ready label. Offline checks do not block startup. Nothing installs automatically.
magi-code --update
Or enter /update while Mission Control is idle. Cargo progress appears in the terminal. After success, magi-code reopens the same session with the same working directory, provider/model, MC_HOME, and explicit theme. It does not replay --prompt. Runs without session persistence restart with --no-session.
The restarted app shows unseen bundled release notes. Press Esc or submit a prompt to return to the conversation. Notes count as seen once displayed; ordinary resumes do not show this view.
Updating waits for session writers to finish. If cleanup still holds a writer after 15 seconds, the update does not start.
--update is a standalone maintenance route: no TTY, provider login, configuration initialization, or session is required. It cannot be combined with other launch options or subcommands. Failed checks, compilation, replacement, or restart return an error, not a success notice. If a TUI update fails, reopen with magi-code --resume <SESSION_ID>.
The updater uses Cargo's locked release build, staging, replacement, and install records. It targets the installation root containing the running executable, including custom cargo install --root locations, and retains the recorded target triple. It does not edit .crates.toml or .crates2.json, fetch GitHub binaries, read Cargo credentials, or use provider credentials to install. Cargo's user-level configuration and registry authentication still apply. Cargo gets one hour to finish; Ctrl-C cancels the build and attempts process-tree cleanup.
Linux and macOS use Cargo's staged rename. On Windows, the updater first relocates the running image and puts an identical old-version copy at its original path, releasing the file lock so Cargo can replace it. Cleanup uses Windows PowerShell at an absolute OS-reported system path, without profiles or repository executable search. It retries deletion for up to two hours; blocked cleanup can leave .magi-code-relocated-* recovery directories beside the executable. Windows PowerShell must be available. A failed relocation attempts to restore the original path and retains recovery files. Cancellation always attempts bounded direct Cargo termination even if tree cleanup fails; errors may require manually stopping remaining build processes. Close other magi-code processes before updating on Windows. Do not run another installer against the same root during an update.
The automatic updater refuses missing, inconsistent, ambiguous, source/Git, renamed, or custom-feature installations rather than guessing their ownership. These require a manual reinstall using their original source and options. For a standard crates.io installation:
cargo install magi-code --version X.Y.Z --locked --force
# Add --root /your/custom/root if needed.
Updates need Rust/Cargo, a working native build toolchain, network access, and permission to write the installation root. A newer release may require a newer Rust toolchain.
Restart without updating
Enter /restart while Mission Control is idle to quit and reopen the running executable without installing anything. No arguments are accepted. The same session, working directory, provider/model, MC_HOME, and explicit theme are preserved; --prompt is not replayed. Runs without session persistence keep --no-session.
Restart restores the terminal, cleans up workers, and releases session writers before relaunching. Pending work blocks the command. If a writer remains after 15 seconds, restart stops with an error; reopen with magi-code --resume <SESSION_ID>. Linux and macOS replace the current process; Windows launches the executable and waits for it to exit.
Build or install from source
git clone https://github.com/magimetal/magi-code.git
cd magi-code
cargo build
cargo run --bin magi-code -- --help
cargo run --bin magi-code --
cargo run --bin magi-code -- --prompt "Find the main entrypoints."
Run a built binary or install the checkout:
./target/debug/magi-code
cargo build --release
./target/release/magi-code
cargo install --path . --locked
Install from a GitHub tag
Tags are release references and a source-install fallback:
cargo install --git ssh://git@github.com/magimetal/magi-code.git --tag vX.Y.Z --locked magi-code
Use main only for a moving development snapshot, not a normal release install:
cargo install --git ssh://git@github.com/magimetal/magi-code.git --branch main --locked --force magi-code
Optional aliases
The crate ships one binary, magi-code, not mc. Add aliases in your shell if useful:
alias mc='magi-code'
alias mcc='magi-code --continue'
To run an uninstalled development checkout from another repository:
alias magi-code-dev='cargo run --manifest-path /absolute/path/to/magi-code/Cargo.toml --bin magi-code --'
magi-code-dev
magi-code-dev --prompt "Summarize this repo."