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](docs/concepts/knowledge.md) instead of grepping, run [targets](docs/concepts/targets.md) instead of raw tools, and let `magus affected ci` prove what a change touched. For agents, see [Agents](docs/guides/integrations/agents.md). The longer argument behind that position, and what it was a reaction to, is in [I think our tools are the problem](https://eli.gladman.cc/magus/blog/2026/08/18/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](docs/scope.md), 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](docs/scope.md). - **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](docs/concepts/sandbox.md). - **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](docs/scope.md). ## 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
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. ```sh 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](docs/setup.md) for platform details, verification, and updates. ### A first look magus targets are written in [Buzz](https://buzz-lang.dev/), 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:[^playground] ```buzz 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: ```sh 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.
 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 |