magus 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 server 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, with 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.
• Providers: the spells a magusfile hands a job to (projects, the remote cache, CI, secrets, review, harnesses, toolchain end-of-life dates), and the contract each one exports.
• 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.
• How gopherbuzz runs Buzz: the pipeline from source to bytecode, the VM, and the baseline JIT, package by package.

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.
• Server 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, which never waits.
• 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.
• Jobs: coordinate work by hand: one person across worktrees, teammates sharing a file, CI checking merged work, and splitting other work.
• Tips and tricks: non-obvious ways to combine subcommands.
• MCP: drive magus from agents over the Model Context Protocol.
• Merge queue: magus queue: queue a pull request by enabling auto-merge, validate stages speculatively, merge each as its own commit; magus supplies the version control and the affected sets.
• 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.
• Server API: the Connect, gRPC, and gRPC-Web contract the server 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 change, newest first, starting with what is unreleased. 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.