magus v0.4.3 is out. See what's new
¶ View generated markdown
2 min read

buzz

The buzz spell declares what a Buzz file IS and how to index it. It is what lets the knowledge graph tell code from a comment or a string in a .buzz source, and what binds the extension to its project. Its one op, scip-buzz, builds the project's Buzz symbol index beside any other index the project has, so magus refs and renames reach Buzz. Running Buzz needs no spell: magus buzz -t <file> executes a file's in-file test blocks through magus's own embedded engine.

Runtime name: buzz (source spells/buzz/)

Version probe: none

Passing arguments to ops

Every op is invoked as buzz["<op>"](ctx, opts?). The first argument is the target's context, which is what carries the execution environment; the optional options map shapes the command itself:

Key Type Description Source
args [str] Extra arguments appended to the resolved command, replacing any trailing defaults the op declares (go-test's ./...), so passing args also states the scope. Omit it and a bare buzz["<op>"]() keeps the defaults and forwards magus run <target> -- <extra> to the tool automatically; pass it to set the arguments explicitly, which replaces that passthrough. To keep the passthrough too, append the target's own args parameter: {"args": ["-race", "./..."] + args}. source
stdin str Data written to the command's standard input. source

Working directory and environment are NOT options: they ride the context, as buzz["<op>"](ctx.withCwd("sub")) and buzz["<op>"](ctx.withEnv({"CGO_ENABLED": "0"})). Only the context reaches the cache key, so an option-table cwd or env would change what the tool did while the key said otherwise; passing either as an option is an error.

Charms (the :charm suffix, e.g. magus run test:rw) are orthogonal: they patch the base argv, while these options add to it. See Charms.

scip-buzz

Indexes the project's Buzz into the cache: magus injects MAGUS_SYMBOL_INDEX with the destination and runs the op from the project dir, which scip-buzz indexes. A project bound to another indexing spell too (go, typescript) keeps that index under scip and builds this one beside it as scip-buzz, so a missing scip-buzz never fails the other index. The workspace root is magus's own, so the paths in the index's symbols are the ones magus resolves files by.

Command: scip-buzz --output $MAGUS_SYMBOL_INDEX --workspace-root $MAGUS_WORKSPACE_ROOT

SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources) that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export. magus documentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml.
generatedspells/buzz/spell.buzzbuzzspelllanguagetools
Last updated (1a76274f)
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.

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.

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.

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.

Knowledge graph

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

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.