magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
4 min read

Uninstall

magus is a single binary, it installs under a prefix you own, and everything it keeps afterward sits where the XDG Base Directory spec says to look. There is no magus self uninstall because there is nothing to unwind. No root, no package database.

Stop the server and the broker first so nothing writes while you delete:

magus server stop
magus broker stop --services

Each exits non-zero when it finds nothing to stop, which is what you get if none is running.

The install

The install script writes three things under INSTALL_PREFIX, which defaults to ~/.local:

Path What
~/.local/bin/magus the binary
~/.local/bin/mgs the mgs shorthand, a symlink to it
~/.local/share/man/man1/magus*.1 the man pages: magus.1, plus magus-<subcommand>.1 for each subcommand

If you installed with a different INSTALL_PREFIX, passed --bin-dir to magus self update, or moved the binary by hand, ask the shell where it ended up:

command -v magus

With XDG_DATA_HOME set, the man pages go to $XDG_DATA_HOME/man/man1 instead. That is the default magus man install resolves, and the one the install script passes through.

State, config, and runtime

Path Default Holds
$XDG_STATE_HOME/magus/ ~/.local/state/magus/ v1.json under history/ (run history, read by volatility detection, the CI forecaster, and bisect), pry_history (REPL history), x/ (the magus x picker, one file per project), memory/ (per-repository agent memory), mcp_token and tokens.d/ (the operator token, and one file per stored token), broker.log and server.log
$XDG_CONFIG_HOME/magus/ ~/.config/magus/ the user-global magus.yaml, the tier under a workspace's own (see Configuration)
$XDG_RUNTIME_DIR/magus/ /tmp/magus-<uid>/ broker.sock, server.sock, and services/. Recreated on the next broker or server start, and cleared for you at reboot

State and config are separate on purpose: config is the kind of thing you sync or commit to a dotfiles repo, and mcp_token must never ride along with it.

Delete any of it. If you are keeping magus and clearing state alone, you lose run history and REPL history; magus recreates the directory on demand.

Windows has no XDG_STATE_HOME by default, so state lands in %LocalAppData%\magus\.

Per workspace

The paths above are user-global. Each repository you ran magus in also holds:

Path What
.magus/ the build cache: cas/, manifests/, logs/, and the mtime memo. Lives in the workspace rather than under XDG; override with MAGUS_CACHE_DIR
magus.yaml, magusfile.buzz written by magus init. Your declarations, tracked in git; delete them only if you are removing magus from the repo itself
.claude/skills/magus-* present only if you ran magus agent install
AGENTS.md the file is yours and magus never writes it; delete the block you pasted between <!-- magus:skills:begin ... --> and <!-- magus:skills:end -->

magus init also wires git, in three places a rm will not reach:

Where What to remove
.gitattributes the block between # BEGIN magus-generated and # END magus-generated
.git/config git config --unset merge.magus.driver
.git/hooks/post-checkout, post-merge, post-rewrite the block between # BEGIN magus-refresh and # END magus-refresh, in each
.git/hooks/post-commit, pre-push the block between # BEGIN magus-drift-notice and # END magus-drift-notice, in each

You can leave these. git treats a merge driver it cannot execute as a plain conflict, and the hooks end in || true, so a missing magus never fails a git operation. The drift-notice hooks are the same shape: delete the block (or the whole hook file, if nothing else uses it) to stop the automatic notice, or run magus server start again after removing it to have it reinstalled.

Shell setup

The lines you added by hand in Shell setup are still there. Depending on which recipes you followed:

Path What
~/.bashrc the source <(magus completion bash) line
~/.zsh/completions/_magus the zsh completion snapshot
~/.config/fish/completions/magus.fish the fish completions
$PROFILE the PowerShell completion block

Plus the export PATH="$HOME/.local/bin:$PATH" line, if you added it for magus and nothing else lives there.

Other install routes

  • mise: mise unuse -g ubi:egladman/magus drops the entry from the config; mise uninstall ubi:egladman/magus deletes the installed version. You need both. For a per-repository pin, edit that repo's mise.toml or pass --path. The XDG paths above are still yours to clean up.
  • Container image: remove the image (docker rmi/podman rmi). It installed nothing on the host, though a bind-mounted workspace still carries its own .magus/.
  • Manual install: delete the binary at whatever path you moved it to, and the man pages if you ran magus man install.
SetupInstall magus from a signed release, verify it, set up your shell, and keep it current with magus self update. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus.
uninstallremovexdgstateconfigcachepathscleanup
Last updated (a9ff8609)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. See wards.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

Broker

The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. See server.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Snapshot

A point-in-time view of live state - the pool's occupancy or a tick of exported metrics - as opposed to accumulated history. See server.

Volatility

A target that fails once and passes on rerun is volatile, as opposed to a regression that started failing and stays failing. magus keeps per-target pass/fail history and a Wilson-score volatility rate to tell them apart and auto-retry the noise. See volatility.

Window

The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.