Install

Binaries for x86_64 and aarch64, built on the runner from the same pinned toolchain the gates ran under — or all four from source, in one clone. Linux only.

Get the binaries

gh release download v0.1.0 --repo ai-nerv/magi --pattern '*-amd64.tar.gz'
tar -xzf magi-linux-amd64.tar.gz -C ~/.local/bin

# the siblings are separate releases. casper and melchior are optional; a memory layer is not
gh release download v0.1.0 --repo ai-nerv/casper    --pattern '*-amd64.tar.gz'
gh release download v0.1.0 --repo ai-nerv/melchior  --pattern '*-amd64.tar.gz'
gh release download v0.1.0 --repo ai-nerv/balthasar --pattern '*-amd64.tar.gz'

What each one buys you

	without it
magi	nothing — this is the one you run
casper	a session with three builtin tools: `read`, `write`, `edit`
melchior	no model and no siblings. The session runs and says so.
balthasar	no session: the memory layer is the store, so magi refuses to start rather than record nowhere. Another program can fill the role — see swapping a program.

Check before you start

magi doctor

It answers everything a session decides at start-up: which configuration was read, which of its lines were kept, what the registry holds and where each entry came from, and whether the siblings actually answer — and whether the program named for each role can fill it at all. Asked, not looked for — a program on $PATH is not a running one, and a socket that accepts is not one that answers.

magi is the only command. It starts a balthasar and a melchior for each session and ends both. doctor reporting “balthasar installed, but not reachable: no socket to try” is correct output outside a session — there is no session, so there is no socket.

Choosing a model

magi holds only the name. Which endpoint it lives at and what credential it takes are melchior's, so ask melchior what this machine can reach:

magi models | head
# then, in ~/.config/magi/init.lua
magi.model = "openrouter/anthropic/claude-sonnet-4.6"

A model that reports ready: false names the variable it wants. Set that, and it becomes ready — nothing else has to change.

All four, from source

One clone holds the four programs as submodules, and its recipes build, run and install them together. It needs oslo and a Rust toolchain.

git clone --recursive https://github.com/ai-nerv/.github nerv
cd nerv
oslo make install   # all four to ~/.local/bin, each config to ~/.config/<name>

recipe	does
`make build`	every binary
`make run`	magi, with the other three fresh from their builds rather than installed. `make run --args doctor` runs `magi doctor` that way.
`make install`	every binary to `~/.local/bin`, and each configuration
`make test`	every suite
`make status`	each checkout: its branch, commits not pushed, changes not committed
`make update`	every checkout to the tip of `develop`
`make push`	push each checkout, then pin what was pushed in this repository

Each recipe goes into each checkout and calls the recipe of the same name there, so make inside a checkout still means that program alone. At an oslo prompt make is enough; elsewhere it is oslo make.

Working on them

Each checkout is a real clone. Commit in it as usual, then make push at the top: it checks all four are on develop with nothing uncommitted, pushes each, and records the new commits in one commit here. A pin to a commit GitHub has never seen is a clone that fails for everybody but you, which is why the push comes first.

A fresh clone is not on a branch. Submodules arrive at the exact commit that was pinned, so make status says detached. To work on one, git checkout develop inside it first — make push refuses until you have, and says why.

One program on its own

git clone https://github.com/ai-nerv/magi && cd magi
oslo make build     # a release binary
oslo make test      # the suite
oslo make verify    # the whole local gate, which is what CI runs
oslo make install   # to ~/.local/bin, and the config to ~/.config/magi

make install overwrites ~/.config/magi/init.lua. Keep your edits somewhere, or expect to re-apply them after every install.

nextconfiguration