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

Friction that carries meaning

A tool made perfectly smooth stops telling you what it did. Every act collapses into the same keystroke, and a pull, a push, a delete and a cache hit read alike. magus keeps resistance where the resistance is the information, after Designing Friction by Luna Maurer and Roel Wouters, with Alexandra Barancova. Their five moves map onto this tool as follows.

  • Discomfort. Output states the uncomfortable fact rather than a reassuring one. A lookup the index cannot vouch for answers "unknown, not absent" (cmd/magus/stale_index.go). A target past its ceiling fails with MGS3011 and is never a skip. A setting magus cannot honor fails the command, as No silent defaults requires.
  • Time delay. A pause sits in front of an act that cannot be taken back, never inside the loop that verifies. The first Ctrl+C only arms a three-second window (confirmWindow, cmd/magus/interrupt.go). The push-ungated guard rule stops a push at a commit no green gate has run on.
  • Engage the body. The verb names the physical act, and the person does it with their own hands. Registry transfers are graph pull and spell pull, never a side effect of another verb. The acts in Manual on purpose stay a person's keystroke.
  • Non-positive. magus publishes what it refused to build and why, in A record of refusals, and a budget it cannot fit is refused at once (MGS3009) rather than queued behind a spinner.
  • Unpredictable self. A refusal hands back the command to run, so the person decides the next move instead of following a default the tool picked for them (A refusal carries its reason).

The test for any new resistance is whether it carries information. The push-ungated catalog entry names the failure it replaced: an advisory that fired on every push having read nothing was "a toll rather than a reminder". Friction that tells the fast caller and the careless caller the same sentence is a toll, and a toll is removed. A finding charged to a change that did not cause it is a toll too, so whoever adds or tightens a rule pays its cost (Rolling out a stricter rule). This principle never slows the loop that verifies: a cache hit stays instant, and the pause belongs to the act that leaves the machine.

The Go SDK

The Go SDK has been read against this page, and holds these rules:

  • Every verdict comes back with its reason and its rule: a types.GuardJudgment names the rule that decided, a JobStatus lists its violations, and a knowledge answer keeps unknown apart from absent.
  • No silent default. A workspace with a magusfile and no linked engine fails with MGS1104, and a library workspace reads no environment unless it is given WithEnv.
  • No helper hides a refusal: the SDK never retries, forks, escalates or re-grades on the caller's behalf.
  • Ambient state appears in the signature. The lease rides ctx through types.WithJobLease, the session is WithSession, the environment is WithEnv, and stderr is WithStderr.
  • A swappable part is a small interface with one option (WithVCSDriver, WithObserver, WithCacheBackend), built only where a second implementation exists.
  • The root package grows only by wrapping code that already exists.

The debt is the rest of magus: the console has not been read against this page, and until it is, its smoothness is unexamined rather than chosen.

Enforced by

Good

The push-ungated rule fires only on the act that leaves the machine, and only when the evidence is missing. Its catalog entry (internal/guard/catalog.go):

push-ungated: a push or `gh pr create` at a commit with no green gate; refused for every session

Bad

Reminder: make sure your tests pass before pushing!

It fires on every push whether or not a gate ran, so the careful caller and the careless one read the same sentence, and both learn to skip it.

See also

PrinciplesPages in this section. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. ScopeThe claim magus is built on: that a correct incremental build already requires a precise model of your repo, and everything else is a read of it. Includes the test for what belongs, the boundaries, and where the claim is strained. Guard hook templatesThe Buzz hook templates Claude Code and Codex run for the magus guard, the checkpoint and the post-compaction brief, with the knobs that adapt them to a host, the version marker that tells you when your copy is stale, and the full source of each.
designprincipleclifriction
Last updated (2df714e8)
Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace 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.

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. Engine in full.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. Sandbox 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.

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.

Tool

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.

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.

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.

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.

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.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.