Glossary
The vocabulary that runs through the rest of the docs. Each term has its own
page at a stable address (glossary/<term>/), so a diagnostic, a review
comment or another page can cite one definition. A term page gives:
- magus's definition, which is the one these docs mean;
- where the wider industry uses the word differently, what it means there and
how magus's meaning differs, without adopting the other meaning;
- one real command or code example;
- where the term is used, generated from the knowledge graph.
Edit a term on its own page under glossary/; the list below is generated
from each page's front matter.
Core model
Workspace
The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace in full.
Project
A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. Project in full.
Magusfile
The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. Magusfile in full.
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. Target in full.
Op
A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.
Spell
A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. Spell in full.
Manifest
The file that declares what a package is: its name, dependencies, entry points and tool config (go.mod, package.json, pyproject.toml, Cargo.toml). How the workspace builds, tests and lints the package belongs in the magusfile, not in the manifest's scripts. Manifest in full.
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. Charm in full.
Ward
A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. Ward in full.
Module
A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. Module in full.
Buzz
The language magusfiles are written in (the .buzz engine). Buzz in full.
Engine
The interpreter a magusfile runs on; magus embeds the Buzz engine. Engine in full.
Execution and caching
Cache
The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.
Affected
The set of projects touched by a change; magus affected <target> runs a target only over them. Affected in full.
Sandbox
The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. Sandbox in full.
Service
A long-running or shared process magus manages across runs, distinct from a one-shot target. Service in full.
Broker
The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. Broker in full.
Daemon
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. Daemon in full.
CI
An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.
Output reference
A short, shareable id such as out1a2b3c for one target execution's captured output; magus query output prints those exact bytes. In OpenTelemetry terms it names a span. Output reference in full.
Trace
OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. Trace in full.
Span
OpenTelemetry's name for one unit of work under a trace: a target execution, whose sub-operations are child spans. An output reference points at a span's captured output. Span in full.
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. Pool in full.
Slot
One unit of the pool's capacity. A target acquires the slots it needs to run (most take one) and releases them when it finishes; the pool tracks capacity (total slots), running (acquired), and queued (blocked). Slot in full.
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. Concurrency in full.
Queued
A target that wants a slot while the pool is full; it blocks first-in-first-out until a slot frees. The dashboard colors a sample with queued > 0 accordingly. Queued in full.
Pool mode
Which pool a run uses: server (one shared pool the daemon owns across every workspace and client) or proc (a per-process pool for a single one-off invocation). Pool mode in full.
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. One-off in full.
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. Remote cache in full.
Snapshot
A point-in-time view of live state (the pool's occupancy or a tick of exported metrics), as opposed to accumulated history. Snapshot in full.
Backfill
The recent history the daemon replays to a dashboard on connect, so its charts start populated instead of empty. It is served from a bounded ring buffer of the last few hundred samples. Backfill in full.
Telemetry and health
Latency
How long an operation takes. magus records latency as OpenTelemetry histograms per family (target execution, cache op, pool wait, and graph query) and reports each as a count, sum, and percentiles. Latency in full.
Percentile
A latency value at a given rank, interpolated from a histogram's buckets: p50 is the median, p95 and p99 are the tail that most latency budgets care about. Percentile in full.
Health
The at-a-glance daemon state derived from the pool: healthy when the pool is reporting, degraded when it reports an error, down when there is no pool. The dashboard color-codes each state. Health in full.
Volatility
A target that fails once and passes on rerun is volatile, as opposed to a regression that started failing and stays failing. magus keeps per-target pass/fail history and a Wilson-score volatility rate to tell them apart and auto-retry the noise. Volatility in full.
Insight and knowledge
Knowledge graph
The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. Knowledge graph in full.
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. MAGUS.md in full.
Insight
The reports magus derives over the graph and history (hotspots, affinity, ownership, trend, volatility, unreferenced). Insight in full.
Hotspot
An insight lens: edit frequency times complexity, the prime refactoring targets. The project view heat-colors the dependency graph by churn; --files ranks individual files. Hotspot in full.
Affinity
An insight lens: projects that change together (temporal coupling). A pair that co-changes without either declaring a dependency on the other is a candidate architectural smell. Affinity in full.
Ownership
An insight lens for author concentration: the primary author and their share, the distinct-author count (the bus factor), and abandonment. Ownership in full.
Trend
An insight lens: the recent half of the window against the earlier half. A positive delta is a rising hotspot; a negative one is cooling. Trend in full.
Diagnostic code
A stable MGSxxxx identifier attached to a magus warning or error, so it can be referenced and looked up; some are guardrails (see wards), others hard errors. Diagnostic code in full.
Design and scope
Scope test
The question every proposed capability has to answer: does it read the model magus already had to build, or does it make magus learn something new about the world? Reads stay small; acquisitions are where a tool loses its shape. Scope test in full.
One-vocabulary rule
Each concept gets one name, used everywhere: target, spell, charm, op. A second word for the same thing is a house dialect, and it costs every reader (and every agent) a lookup that never ends. One-vocabulary rule in full.
Agents
Agent
A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent in full.
An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.
Harness
The deterministic scaffolding around the work on a change, for a person or an agent: compiler errors, formatters, linters, checks, gates, leases and hooks, placed at points a person chose. Around an agent's loop, magus supplies one and keeps it outside. Harness in full.
Skill
A packaged set of instructions an agent host loads when a task matches its description: a directory holding a SKILL.md. magus ships its magus-* skills in the binary and writes them with magus agent install. Skill in full.
Sessions and leases
Session
An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it. Session in full.
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. Invocation in full.
Window
The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session. Window in full.
Attention request
A durable record that an agent is blocked, opened by a magus session notify event and held until a person disposes it. Nothing closes one on its own. Attention request in full.
Dispose
The human act of closing an attention request: a judgment rendered, recorded with who and why. Distinct from resolving a review thread or a merge conflict: a disposition answers a request; it does not merge anything. Dispose in full.
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 daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job in full.
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. Run in full.
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. Lease in full.
Lease id
The short identifier a worker carries (the --lease flag, or the magus.lease member of the W3C BAGGAGE environment channel) so its runs, journal facts, and guard verdicts attribute to the job it holds. Letters, digits and -_./: only. Lease id in full.
Spawn claim
What a spawning tool said about itself in the environment: TRACEPARENT (the W3C trace and the parent span this process runs under) and the magus.spawner baggage member (a label for whoever spawned it). magus records each verbatim beside the invocation's own minted span id, and no verdict reads any of them; the ancestry is a relation between recorded invocations, the way a process tree is a relation between pids. Spawn claim in full.
Advisor
One read-only check from the advice suite: it reads the changeset through magus and writes one titled section of findings. The same advisors run as a pull request comment in CI and inside magus diff --impact locally. Advisor in full.
Console
Console
The browser app that reads a magus workspace: a tabbed, tiling page hosting the log viewer, graph explorer, dashboard, and activity trail. It is a separate static app, not something the daemon serves; the daemon exposes a loopback API it calls: read-only views plus one bearer-gated job-control service for maintenance jobs. Console in full.
Console app
One of the console applications (Runs, Log Viewer, Graph Explorer, Dashboard, Activity Trail, Settings), mounted into a tab or a pane. Each is single-instance. Console app in full.
Pane
A split within a tab. Splitting divides the focused pane along its longer side, so the same action tiles side-by-side on a desktop and stacks on a phone; a tab with no split is a single pane. Drag the divider to re-weight the split. Pane in full.
Chord
A key combination bound to a console command, written mod+k, where mod is Cmd on macOS and Ctrl elsewhere, so one binding fits both. Every chord is rebindable (Settings > Keybindings), and a command remains reachable from the command bar whether or not it has one. Chord in full.
Command bar
The console's runner: one searchable list of every command and its chord, opened with mod+k. It is the discoverable route to any action: the menus and chords dispatch the same commands it does. Command bar in full.
Live link
The URL that points an app at a running daemon. The daemon serves the console from its own loopback origin, so the link is that origin plus the app path and a bearer token in the fragment (http://127.0.0.1:7391/console/graph/#token=...). The daemon prints it; the console consumes the token, stores it, and strips it from the URL, so the secret never lingers in history or a copied link. The origin must be literal loopback: localhost and hostnames are rejected before any request. Without one, an app reads only what rides in the link itself. Live link in full.
See also
- Conventions: how to read the placeholders,
shell commands, and admonitions used across these pages, and the
term page template.
- Targets: the fuller Target-struct glossary (Path, Name, Files)
for magusfile authors.