Development

A fast, cross-platform task orchestrator for polyglot monorepos. One binary, no second toolchain to install. Targets are programs, not YAML.

Change a file and magus works out which projects it reaches, rebuilds only those, and caches every result so the same work never runs twice.

magus informs; it never decides. It hands you everything it knows about your repository - what a change reaches, which files are generated, where a symbol is used - and the call stays yours. It was built for humans, not for agents: agents drive it well anyway, because an interface legible to a person is legible to anything, and that ordering is the design.

One command, three runs: cold, fully cached, then narrowed to what a change reached.

Why magus exists

magus is the tool you type all day: build, test, lint, and ask the repo a question. Two problems shape everything else on this page. The first is what those commands cost you in time. The second is what they need you to already know.

The tools you run in a monorepo, you run all day. Build, test, lint, switch branches, do it again. So friction compounds fast. A few wasted seconds a run, one flaky target, a teammate's botched merge that starts failing on your checkout, and now you are babysitting the build instead of shipping the feature. Tooling this central earns its place by getting out of the way. It should be fast, and genuinely good at the narrow thing it does.

The other half of the job is knowledge. Monorepos outgrow the people and tools reading them. Humans grep; AI agents grep faster and guess more confidently; both drown in generated files, unfamiliar patterns, and dependency chains nobody holds in their head. magus takes the opposite bet. The build tool already has to know the repo precisely, down to every project, every target's inputs and declared outputs, and what a diff reaches, so it hands that knowledge back as answers instead of leaving everyone to rediscover it.

That is the rule for the whole surface. Every verb answers a question, deterministically, from declared sources: which projects a change affects, whether a file is generated and by what, where a symbol is used, how two things relate. Nothing in magus decides for you, plans for you, or injects itself into your workflow. Answering is the tool's job; deciding is yours, or your agent's.

The same discipline serves both audiences. A teammate on day one and an AI agent in a fresh session have the same problem: a repo they cannot yet trust their guesses about. magus gives them the same fix. Query the knowledge graph instead of grepping, run targets instead of raw tools, and let magus affected ci prove what a change touched. For agents, see Agents.

The longer argument behind that position, and what it was a reaction to, is in I think our tools are the problem.

Who this is for

If any of these is your week, the rest of this page is worth your time:

• You came back to your own project after three months and cannot remember which command is the real one.
• Your CI runs everything on every commit, you know most of it was pointless, and you cannot prove which part.
• You inherited the build. Whoever wrote it has gone, and you need to change one step without discovering what else it fed.
• You run more than one language in one repo, and your task runner was built for one of them.
• Your agent greps and guesses. It is fast, it is confident, and it is wrong in ways that take longer to catch than to fix.
• You have a .env full of tokens you keep meaning to clean up, in a shell where everything you launch inherits them.
• Someone asked why a target rebuilt and the honest answer was a shrug.
• You stopped trusting the cache and turned it off, and now everything is slow and at least it is honest.
• A merge changed the lockfile and nothing told you. Your next command ran against stale dependencies and failed somewhere unrelated, and the fix was a command nobody printed.
• Your task runner installs through the package manager it is supposed to be running. When it breaks you fix it by upgrading the toolchain you were using it to pin.
• Generated files keep landing in review and nobody agrees which are safe to edit by hand.
• Getting the build working is its own project, and it was supposed to be the thing that let you work on the other one.

There is one shape under all of them: a question about your own repository that something already knows and nothing will tell you.

Two of those waste whole afternoons, so here is what magus does about them.

The stale install. magus runs your package manager's install as a step of the build, not as something you are expected to remember after a merge. It does not try to work out whether the install is needed, and that is deliberate: the obvious check - does node_modules exist - is wrong in the case that matters, because an interrupted install leaves a directory that exists and is incomplete. So the install runs every time and lets the package manager be the judge. That costs about a second on a warm tree and fails loudly when the lockfile and the manifest disagree.

The bootstrap loop. magus is one binary and installs through none of the toolchains it drives. A task orchestrator that arrives through the package manager it orchestrates has put itself downstream of the thing it is meant to control: the failures arrive oblique, there is rarely anywhere sensible to attach an error explaining them, and the repair is to upgrade the runtime you adopted the tool to pin. That boundary is stated as a rule in Scope, not as a preference.

If you only have one project

Most of what is above does not depend on having several. A target's cache key is built from that target's own declared inputs, so a warm re-run skips work in a one-project repo exactly as it does in this repository's ten. The knowledge graph indexes symbols, docs and generated files, not just the edges between projects. One vocabulary is worth more on your own, not less, because there is nobody else to ask what the build step was called.

What does thin out is the affected set. With one project, "what did this change reach" has only one answer, and the shard planning behind magus affected ci has nothing to plan. That is the part that starts paying when you split out a second project, which is also why magus init scaffolds exactly one and expects to be right for a while.

Who it is not for

Stated plainly, because a list of strengths on its own is advertising:

• You need a build farm. There is no remote execution. magus caches results and shares them; it does not run your work on someone else's machine.
• You want your toolchain versions installed for you. magus compares what ran against what you declared and stops there. It will not select, install, or switch a version - see Scope.
• You need a sandbox that fails on undeclared reads. magus's sandbox is a supply-chain defense: off by default, with no kernel layer on macOS. If you want Bazel's hermeticity guarantee, magus does not offer it and should not be read as claiming it - see Sandbox.
• You want your build steps to run in containers. magus will not require a container runtime, because a task orchestrator that needs one cannot be used to bootstrap the machine it runs on - and it offers no opt-in container isolation either. (The container charm changes what a target produces, an image instead of a binary; the build still runs on the host.) If a fixed execution environment is what you are buying, a container-native runner is the better tool - the reasoning is in Scope.

How it works

Five ideas carry most of the tool. Each has a deeper page; this is the short version.

Affected sets

magus keeps a dependency graph of your projects and knows which files each target reads. Change a file and magus affected <target> runs only the projects that change can reach, in dependency order. magus affected ci runs the full pipeline over that set, so CI does the least work a change requires and still catches breakage in a project you never opened. See CI.

Content-addressed caching

Every target declares its inputs and outputs. magus hashes the inputs, and if it has already seen that hash it replays the stored output instead of running the work again. The cache is a plain content-addressed store on disk (SHA-256): the input hash is the key, and the stored outputs are addressed by their own content hash, so a replay is a byte-for-byte reproduction of the recorded run.

The knowledge graph

Most tools that offer you a codebase graph are observers: a separate indexer scans the repo, infers the structure, and can be wrong in ways nothing warns you about. magus is not observing - it is the thing that builds the repo, so it already has to know every project, every target's declared inputs and outputs, and what a diff reaches, and getting any of that wrong breaks builds loudly. The graph is that same knowledge handed back: a byproduct of being the source of truth, never an inference about it. No LLM pass, no fuzzy linking; every edge traces to a declaration you can open.

magus query "kind=target lint" finds nodes, magus explain <node> shows a node's edges and what reaches it, and magus refs <symbol> lists where a symbol is defined and used from a SCIP index.¹ The same graph answers "is this file generated," "what does my diff touch," and "how do these two things relate" without grepping. See the knowledge graph, including what this graph deliberately is not.

One vocabulary

magus names a thing once and reuses the name everywhere, in the CLI, the config, and the graph. A target is a unit of work such as build, test, or lint. A spell is a language adapter that supplies a target's operations (the go spell provides go-test; the buf spell provides buf-lint). A charm is a modifier applied to a run, like rw for read-write or cd for continuous delivery. An op is a single tool invocation. Learn the four words and the rest of the surface reads the same way.

There is a terminal UI. It stays out of your way

A run pins its progress, failures group by project beside their output, and the picker searches the graph as you type.

The band at the bottom holds still while your output scrolls past it. Nothing is cleared, the alternate screen is never touched, and your scrollback survives - so selection, copy and paste keep working the way they always did. Every one of these surfaces degrades to plain text when there is no terminal to draw on.

Getting started

Install

magus ships as a single self-contained binary, so there is no second toolchain to install.

curl --proto '=https' --tlsv1.2 -sSf https://eli.gladman.cc/magus/install -o install.sh
less install.sh
sh install.sh

Reviewing the downloaded script before executing it lets you audit the URL, verification, and installation steps instead of piping an unreviewed network response directly to your shell. See the Install guide for platform details, verification, and updates.

A first look

magus targets are written in Buzz, a small typed scripting language it embeds. A magusfile.buzz at the repo root declares your targets as exported functions - each one composes operations from the spells you bind:²

import "magus";
import "magus/spell/go";

magus\project({ "spells": [go] });

// Every exported function is a runnable target. It receives a magus\Context,
// the handle it uses to declare what it needs and hands to every op it runs.
// magus caches each target's result and runs it only when a change reaches
// this project.
export fun build(ctx: magus\Context, args: [str]) > void { go["go-build"](ctx); }
export fun test(ctx: magus\Context, args: [str])  > void { go["go-test"](ctx); }
export fun lint(ctx: magus\Context, args: [str])  > void { go["golangci-lint"](ctx); }

// format is read-only by default: go-fmt reports files that need formatting, and
// go-mod-tidy runs with --diff so it fails if go.mod/go.sum have drifted. They take
// DIFFERENT write charms, because they are not the same risk. gofmt is offline, so
// the same tree always yields the same bytes - `magus run format:rw` rewrites the
// code. Tidy resolves against the module proxy, so what it writes depends on what
// upstream serves today; that is a second, deliberate ask:
//   magus run format:rw          formatting only; go mod tidy still just reports
//   magus run format:rw,relock   also let go mod tidy amend go.mod and go.sum
export fun format(ctx: magus\Context, args: [str]) > void {
    go["go-fmt"](ctx);
    go["go-mod-tidy"](ctx);
}

// 'ci' is the anchor `magus affected ci` keys off: it composes the pipeline
// by declaring the targets it needs.
export fun ci(ctx: magus\Context, args: [str]) > void {
    ctx.needs(build, test, lint, format);
}

Point magus at that repo and each command returns an answer and stops:

magus ls                                  # which projects exist
magus run test                            # run a target, cache the result
magus affected ci                         # the pipeline, over only what your diff reaches
magus query "kind=spell"                  # what the graph knows
magus describe file docs/gen/index.html   # is this file generated, and by what

Nothing here plans a workflow or decides for you. magus describe file tells you a path is a generated output so you skip its diff; magus affected ci tells you which projects a change reaches so you run no more than that.

Architecture

One process (magus server start) exposes the workspace through two standing listeners, one per audience, and every browser page is a separate static asset; the binary serves no HTML. A third listener is raised only on demand: "share to phone" opens a time-boxed LAN listener that serves the read-only console to a phone on the same network, then tears itself down.

Four figures, one subject each. They were one flowchart until it carried roughly thirty-five boxes, which is the point at which a diagram stops being read and starts being skipped.

The HTTP surface

Agents and the console share one guarded front door: a DNS-rebind check, a bearer token and a CORS policy sit in front of /mcp, /api/v1, the Connect services and the share endpoint. The health endpoints are the deliberate exception, so a probe never needs a credential.

The local path

A CLI invocation never goes over HTTP. It dispatches across a private unix domain socket into the concurrency pool and the three registries the daemon keeps warm. Sharing a graph is the one case that spawns a separate short-lived loopback server.

What keeps it warm

File watchers, the SCIP auto-indexer and a coalesced graph-build job all exist to keep one thing current: the workspace registry, which holds the daemon's only warm copy of the knowledge graph.

Sharing to a phone

The LAN listener is the only part of magus a second machine can reach. It is minted by a loopback-only endpoint, time-boxed (fifteen minutes by default), carries a read-only token, and serves no MCP, share or mutating route at all.

Because the two listeners are separate, they can diverge: the socket can be healthy while the HTTP/MCP endpoint failed to bind, which is why magus status reports each one on its own line.

The browser console

magus is fully featured from the terminal, so everything here is optional. Alongside the CLI, the daemon can drive a set of read-only browser apps.

Want to see it first? Open the live demo: no install, no daemon. It fills the dashboard with synthesized activity, streams a build into the log viewer, and lets you jump between every app in demo mode. Everything below runs against your own daemon instead.

The apps

The apps ship as one console; each link below opens it on the matching app.

Dashboard Pool, cache and daemon health, live	Graph Explorer Targets, spells and their dependencies	Log Viewer Any run's captured output, streamed or replayed
Activity Trail What agents did, and when	Diff Review the working tree, paired with an agent	Work plan Who holds which lease, and where two of them overlap (press p)
Big Picture The same dashboard with the console's own chrome gone, for a wall display (press b)
Diff, mobile The file index folds to a rail; split view falls back to unified	Log Viewer, mobile The waterfall keeps its drawn size and scrolls, rather than shrinking its labels away	Dashboard, mobile Tiles stack, the rail gives way to the launcher grid, and controls take a 44pt touch target

• Dashboard shows live daemon health, the concurrency pool, running targets, cache activity, and the live lease plan.³
• Graph Explorer navigates targets, spells, and their dependency graph (magus graph export --open).⁴
• Log Viewer reads or streams any past run's captured output (magus query output <ref> --open).⁵
• Activity Trail shows recent MCP calls, agent-command observations, background jobs, and config changes.⁶
• Diff annotates the working tree's uncommitted changes - generated vs source, blast radius, coverage - and hosts the human half of a paired review.

How it stays on your machine

These are add-ons, not a runtime you depend on. Two decisions keep them that way.

The binary embeds no UI

magus never embeds a web server that ships a UI, and a released binary carries no pages: the console is a separate static site (rendered from docs/ at deploy time, hosted at eli.gladman.cc/magus, or self-hosted from any file server). What the daemon exposes over loopback is a small API - read-only views (/api/v1/...), one bearer-gated job-control service for maintenance jobs, and the MCP endpoint. It will also serve a console build you point it at on disk (console/gen, or MAGUS_CONSOLE_DIR) so you can host your own copy, but it ships none and 404s /console/ until one is built.

Your data never leaves the loopback

The hosted page talks only to 127.0.0.1/[::1], a loopback lock it enforces before any request, or it receives your graph inline through a URL fragment. Nothing is uploaded. You can drop the UI entirely: set console.enabled: false and the daemon runs fine without it, serving no browser API at all. See the Console reference.

Working with AI agents

A tighter feedback loop does more for an agent working in your code base than a larger model does, and most of that loop already exists: the build, test, lint, format, and cache scripts you wrote so developers could set up an environment. magus is the hookup. Those same scripts become what the agent runs, deterministic and fast.

magus treats an AI agent and a new teammate as the same kind of user: someone who cannot yet trust their guesses about the repo. It ships an agent surface built on the knowledge graph, so an agent asks magus instead of grepping and guessing.

• Installable skills teach an agent to query the graph, run work through targets, and triage generated files. For Codex, run magus agent install .agents/skills and paste the always-on AGENTS.md block it prints. Claude Code uses .claude/skills; there is a setup page per host behind Agents.
• The committed MAGUS.md is a routing index, regenerated from the graph, that points an agent at the exact query for a given question.
• The MCP server the daemon exposes lets an agent call magus tools directly over the protocol rather than shelling out.⁷
• The guard hook judges a command or a write before an agent runs it, from rules that live in the binary rather than in per-host integration code. The host-shaped wiring is a template you copy and own, so a host magus has never heard of gets the same rules, and one that changes its hook surface next month is your few-line edit instead of a magus release. Doctrine records why it works that way.

Full detail, including which tools exist and how to connect, is on the Agents page.

Documentation

Full docs live at eli.gladman.cc/magus.⁸ The major sections:

• Core concepts: Targets, Spells, Charms, Operations, Services
• Running at scale: CI, CI providers, Daemon, Remote caching, MCP, Telemetry
• Reference: Man pages, Standard library modules, Testing, Debugging, Output references, Tips and tricks

Inside a workspace, the entry point is the committed MAGUS.md: a generated routing index of the workspace's projects, targets, and the exact knowledge-graph queries that answer questions about them. Projects can carry their own (this repo commits one for docs/ and for each project under libs/), scoped to that project. They are generated by magus describe graph -o markdown via the generate target; regenerate them, never hand-edit.

Development

magus is built and tested by magus, so this repository is a magus workspace like any other. That means parts of the contributor reference are generated from the workspace's own graph rather than written, and can show things a hand-maintained page cannot:

• Project catalogs - one page per project: every runnable target, what it depends on, which toolchains it drives, and a run-order diagram built from the real ctx.needs edges.
• Workspace dependencies - the projects in dependency order, with each one's blast radius: how many projects a change there can reach. Read it before you touch libs/gopherbuzz.
• Contributing guide - the conventions worth knowing before opening a pull request, including the benchmark-evidence rule for performance changes.
• Configuration reference - the magus.yaml keys and the MAGUS_* environment inventory.

The architecture diagram above tags each runtime component with the package it lives in, which is the quickest map of where code goes.

Building from source

magus builds magus, so the binary comes out of a magus target like anything else in this workspace:

mise install              # the pinned Go, Node, and esbuild
magus run go-build .      # writes ./magus

go-build regenerates the compiled built-in spells before it links, so the binary never embeds stale bytecode. It is the target to use over build, which also runs the format and image stages.

Do not have a magus yet? Install a release and point it at your checkout - then every build after that is the command above.

Failing that, a clone with no magus and no release can bootstrap one with Go directly. This is the only place a raw go build belongs, and only to produce the binary that runs everything after it:

GOEXPERIMENT=jsonv2 go build -o magus ./cmd/magus   # bootstrap only
./magus run go-build .

GOEXPERIMENT=jsonv2 is not optional: mise.toml sets it for this repository, so a build without it differs from every other build here and shows up later as generated-file drift that is not yours.

Running the tests

Run the tests through magus itself, since the whole point is that magus builds and tests magus:

magus run ci