magi-code 0.77.1

Repository-aware CLI coding agent for terminal work
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Installation and updates

[Feature docs index](README.md) ยท [Repository README](../../README.md)

## Install and start

You need [Rust 1.88.0+ with Cargo](https://rustup.rs/), network access for live provider calls, and a configured provider. Built-in content search does not require ripgrep; `ffgrep` remains an alias for `grep`.

```sh
rustc --version
cargo --version
cargo install magi-code --locked
```

This installs the latest published version. To select the README's release explicitly:

```sh
cargo install magi-code --version 0.77.1 --locked
```

Make sure Cargo's bin directory is on `PATH`, then launch from the repository you want to work in:

```sh
export PATH="$HOME/.cargo/bin:$PATH"
cd /path/to/your/repository
magi-code
```

Connect a provider in Mission Control:

```text
/login
/login openai-codex
```

Use ChatGPT/Codex OAuth, an Anthropic API key, or a configured OpenAI-compatible provider. See [Provider authentication](provider-authentication.md).

Mission Control starts by default and requires TTY stdin/stdout. To queue its first prompt:

```sh
magi-code --prompt "Summarize this repository."
```

For non-interactive frontend clients, use `magi-code --app service` and the [JSONL protocol](application-service.md). Plain one-shot output and positional prompts are not supported.

## Update with Cargo

Mission Control checks crates.io after its first frame and every four hours while open. A newer stable, non-yanked version produces a local notice with `/update`. Checks run on one background worker with a 15-second timeout and bounded response size. Offline or failed checks do not block startup; a version is announced once per launch. Nothing installs automatically.

```sh
magi-code --update
```

Or enter `/update` in an idle Mission Control session. It rejects arguments and active work, restores the terminal, finishes cleanup, releases the session writer, and runs the same updater. Cargo progress appears in the normal terminal. After success (including already up to date), magi-code reopens the **exact session ID**, not the most recent session. It preserves cwd, `MC_HOME`, selected provider/model, provider-keyed auth, and an explicit theme override; it never replays `--prompt`. Without session persistence, it restarts with `--no-session`.

A never-used session gets a local creation marker so its ID can be resumed. Existing conversation history is not rewritten. The handoff checks for any remaining writer for up to 15 seconds; if background cleanup still holds it, no update starts.

`--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:

```sh
cargo install magi-code --version X.Y.Z --locked --force
# Add --root /your/custom/root if needed.
```

Rust/Cargo, a working native build toolchain, network access, and permission to write the installation root are required. A newer release can require a newer Rust toolchain. Release publication remains manual; no binary-release workflow is used.

## Build or install from source

```sh
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:

```sh
./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:

```sh
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:

```sh
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:

```sh
alias mc='magi-code'
alias mcc='magi-code --continue'
```

To run an uninstalled development checkout from another repository:

```sh
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."
```