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

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 - 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.
  • 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.
  • 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.
documentationdocsgetting-startedguideindexoverview
Last updated (6629039f)
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.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. 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.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Ward

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

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

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

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. See engines.

Cache

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

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

Service

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

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.

Trace

OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. See telemetry.

Pool

The concurrency pool: the shared set of slots that caps how many targets run in parallel on one machine. Its capacity defaults to MAGUS_CONCURRENCY, then 4 on GitHub-hosted runners, then min(NumCPU, 8); magus status and the dashboard report it live. See server.

Concurrency

How many targets run at once. It is bounded by the pool's capacity and set with --concurrency, MAGUS_CONCURRENCY, or the concurrency config key. See server.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Invocation

One magus process's recorded facts - the targets it finished, their outcomes, the lease it acted as, and the session it ran in when a host delivered one - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

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.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.