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

FAQ

Short answers with a link to the full story.

What is the difference between a spell, a target, and a charm?

A target is a named operation on a project (build, test, lint). A spell teaches magus how a tool performs that operation (the go spell knows go build, go test). A charm modifies how a target runs without changing which target (rw to write in place, gha for GitHub Actions output). Target = what, spell = how, charm = in what manner. See targets, spells, charms.

Why did magus run goBuild work when my target is go_build?

magus normalizes every target name to canonical kebab-case on both sides: when a magusfile declares a target and when you reference one, whether on the CLI, in a magus\needs literal, or in a per-target policy key. go_build, goBuild, and go-build all normalize to the same registered target, so any spelling reaches it - there is exactly one target, not a table of aliases. This does not apply to a spell op after :: (go::golangci-lint matches verbatim) or to a Buzz map subscript like ts["tsc"]. See targets.

Why is my format run read-only? How do I make it write?

Every run is read-only by default, so a check never surprises you by rewriting files. Ask for writes with the rw charm: magus run format:rw. There is no --write flag; the :rw suffix is the one way. A workspace can opt into writing by default with default_charms: [rw]. See charms.

How does magus decide whether to rerun a target or use the cache?

The cache is content-addressed: a target's outputs are keyed by the SHA-256 of its declared inputs (needs, provides, claims). Unchanged inputs replay the previous outputs instead of rerunning. magus caches what a target declares, not what it touches, so correctness is a declaration contract. See cache.

How do I build only what changed?

magus affected <target> runs a target for every project a VCS diff touched, plus everything downstream of those projects in the dependency graph. magus affected ci is the monorepo CI workhorse. See affected.

Do I have to run the daemon?

No. magus runs fine without it. The daemon keeps spells and services warm across invocations and backs the MCP server; it starts on demand and is optional. Disable it with MAGUS_DAEMON_ENABLED=false. See daemon.

How do I add support for a tool magus does not know?

Write a spell. For a one-off, a magusfile function target calling os\exec is enough; for shared vocabulary, author a spell whose handler returns a Command (or a Service for a long-running process). magus init spell scaffolds one. See spells and the authoring editor setup.

Why did two charms give me a warning about one being "overridden"?

Two active charms edited the same argument, so one silently wins (by alphabetical name) and the other has no effect. That winner is an accident, not a decision, so magus warns. Make the two charms edit different arguments, or drop one. See charms.

Can I run a single spell operation directly, bypassing targets?

Yes, with the :: hatch: magus run go::go-vet api runs the go spell's go-vet op in project api. It is an escape hatch for one-off invocation, not the everyday surface; a target is the normal way in. See operations.

Is my telemetry or cache sent anywhere?

No. magus operates on your files and your infrastructure. Telemetry is off by default and, when enabled, ships to your OTLP collector, not a magus-operated backend. The remote cache is your storage. See telemetry.

How do I see what a target will actually run before running it?

magus describe target <path:target> renders the fully-resolved command (charms applied) without executing. Add --explain to trace each charm's edit, or a :charm suffix to preview it. For a service target it also shows the readiness and stop plan. See charms.

Where do I configure magus?

magus.yaml at the workspace root. magus config view prints the resolved configuration; every key is documented in the config reference.

See also

ReferencePages in this section. 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. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground.
faqquestionsspellstargetscharmscacheaffecteddaemon
Last updated (e0463131)
Earlier changes on this page (1)

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.

Operation

A single tool-native command a target composes; the middle of the work hierarchy (Spell to Operation 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.

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.

Affected

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

Service

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

Daemon

The background magus host that owns shared state such as services and the warm knowledge graph. See daemon.

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.

One-off

A single magus invocation that runs a target and exits, using a per-process pool; the opposite of the long-lived daemon or a service. See daemon.

Remote cache

A CI-only backend that shares content-addressed artifacts across runners: a cold machine replays a build another runner already did instead of rebuilding. Every remote artifact must be signed by a trusted key. See remote-cache.

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.