Documentation

New to magus? Install it, skim the two core ideas below (Targets and Spells), or try it live in the playground without installing anything.

Philosophy

A build system sits in the hot path of development. You touch it constantly, so every small friction compounds; it earns its keep by staying out of the way.

magus does not try to define what "build", "test", or "lint" mean for your tools. That is the job of spells: libraries of tool-native operations. The go spell exposes ops like go-build, go-test, go-vet, golangci-lint, and go-fmt; the rust spell cargo-build, cargo-test, cargo-clippy, and cargo-fmt; and your magusfile composes them into the canonical targets you run (build, test, lint, format). magus handles the orchestration around them: it computes the affected projects from a change, caches their results, and runs only the minimum.

That machinery stays transparent. The cache, the daemon socket, and the run log are all files on disk; inspect them with ls and cat.

Doctrine records what magus automates and what it leaves to your judgment; Scope records what belongs in the tool at all.

Getting started

Prefer a linear, written walkthrough? The Getting started guide runs install to first ci pipeline as prose. The quick version:

1. Install magus. A single self-contained binary. The Install guide covers install, verification, and updating.

2. Initialize your workspace. From the root of your repo:

magus init

This writes magus.yaml, stubs a starter magusfile.buzz, and wires the VCS merge driver.

3. Declare targets and run them. Targets are exported functions in magusfile.buzz - no registration call needed. Each one composes operations from the spells you bind.

import "magus";
import "spells/hello";          // ./spells/hello/spell.buzz

magus\project({ "spells": [hello] });

// Each exported function becomes a runnable target.
export fun build(ctx: magus\Context, args: [str]) > void { hello.build(); }
export fun test(ctx: magus\Context, args: [str]) > void {}

// 'ci' is the conventional anchor `magus affected ci` keys off.
export fun ci(ctx: magus\Context, args: [str]) > void {
    ctx.needs(build, test);
}

magus ls            # list registered projects and their targets
magus run build     # run a single target
magus affected ci   # run ci only for the projects your changes touched

Core concepts

Start here to understand the model magus is built on.

• Workspace and projects - how magus discovers projects, the magusfile layout, depends_on, and monorepo patterns.
• Targets - the named operations you run (build, test, lint), declared as exported functions in a magusfile.
• Dependencies - magus\needs versus depends_on, the cross-project fold between them, and how they interact with the cache and the affected set.
• Spells - language/toolchain adapters that provide tool-native operations (go-build, go-test, ...) for your targets to compose. See Spells vs Targets for where the line falls.
• Charms - execution modifiers attached with : (for example lint:rw to let a read-only target write).
• Operations and the work hierarchy - how a run is scheduled and parallelized across projects.
• Cache model - needs/provides, the content-addressed cache key, invalidation, and replay.
• Sandbox model - the threat model and allowlist semantics that confine spell execution.
• Services - long-running service ops, shared one instance across dependents and invocations, with sprawl and misuse guards.
• Wards - coded guardrails that reject a resolved op whose argv contradicts its kind (a detached service, a watching command).
• Knowledge graph - the deterministic, cache-backed graph of the magus domain that magus query/explain/path and agents read instead of grepping.
• Diagnostics - every error is a pointable coded diagnostic (MGSxxxx) with a handwritten resolution page and a queryable graph node, written for a human to act on rather than parse.
• Engines - how magus loads and evaluates a magusfile.

Going further

Once the basics click, these cover running magus at scale and in CI.

• CI - compose a ci target with magus\needs, and the shared-cache trust model.
• Daemon and concurrency - one persistent process, one shared pool across every client.
• Concurrency - the two scopes of parallel work: the scheduler within a run, and the cross-process workspace lock between separate magus invocations (with MAGUS_NO_WAIT).
• Remote caching - share the build cache across machines and CI, with a signing-based trust model.
• Editor setup - wire your editor to magus buzz lsp for magusfile completion, hover, and signature help.
• Git integration - the generated-file merge driver and what no forge will run, settling conflicts with magus vcs resolve, and the rule every magus hook obeys: a hook hands off work, it never does work.
• Debugging - the interactive REPL, magus\pry() breakpoints, and stepping through a target.
• Profiling - find the magusfile line filling memory, read the low-headroom warning, and fix the string-building pattern that costs gigabytes.
• Tips and tricks - non-obvious ways to combine subcommands.
• MCP - drive magus from agents over the Model Context Protocol.
• Review - read a change, draft remarks as you go, and send them to the pull request they belong to, with the review's own conversation rendered beside the code.
• Telemetry - OpenTelemetry traces and metrics.

Coming from other tools

• Coming from Nx - a terminology map and porting sketch for teams migrating a workspace from Nx.
• Nx integration - experimental: map an existing Nx workspace into magus with a workspace provider, keeping Nx as the thing that runs the work. Ships in no release; you copy a spell in by hand.

Reference

Generated man pages for every command:

• magus - the umbrella page: global flags, environment variables, and the full subcommand list.
• magus run - run a target; the everyday command.
• magus affected - run targets only for projects a change touched, with sharding and bisection for CI.
• magus ls and magus describe - inspect projects, targets, and the dependency graph.
• magus watch and magus x - re-run on change, and the interactive target picker.

The magusfile API and diagnostics:

• Configuration - every magus.yaml key with its MAGUS_* environment variable, CLI flag, and type.
• Standard library modules - fs, os, http, json, crypto, and the rest of the magusfile API.
• Daemon API - the Connect, gRPC, and gRPC-Web contract the daemon serves, generated from the .proto schema. Every service, method, message, and enum, so you can build your own client or frontend against it.
• Spells reference - the built-in spells (go, rust, typescript, python, docker, buf, cosign, buzz, markdown, bash), their ops, and paste-ready examples you can dry-run in place.
• Diagnostics and wards - every problem magus reports carries a stable MGSxxxx code with a dedicated explainer. Some are hard errors; others are wards, guardrails that flag a risky op before it runs (for example a detached service op, MGS5002). Browse by family: magusfile, race, sandbox, services, and knowledge graph.
• Conventions - how placeholders, shell commands, runnable examples, and admonitions are written across these docs.
• Glossary - the core magus vocabulary (workspace, project, magusfile, target, spell, operation, charm, ward, module, engine) defined in one place.
• Changelog - every released change, newest first. Pages that call out a behavior change name the release it landed in; this is where that release is written up.
• Tags - every topic, with the pages carrying it. The one route through these docs that ignores the section tree, so it finds pages a directory walk would not put next to each other.