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

No news is good news

Unix settled this decades ago: a command that worked says nothing, and the exit status carries the verdict. magus keeps that, and it matters more now. A person skims past a wall of green and misses the one red line. An agent pays for every line in its context on every call after it, so a chatty pass is a tax on the whole session.

So a quiet run prints its address and stops. With -s, a pass is one ref line; a failure adds the diagnostics, a bounded tail of the log, and the path to the rest. The full log is never lost, it is one magus query output <ref> away, so there is no reason to print it in case someone wants it. A warning about something that works is noise (No silent defaults), and a message that only says a thing failed has wasted the one moment it had the reader's attention (A refusal carries its reason).

Quiet is not the same as hidden. Asking for more is always one flag away (-v, -vv, -o json), and the guard steers an agent to -s rather than to a pipe through tail, which would hide the exit status along with the noise.

Enforced by

  • -s stays quiet until something fails, then prints the diagnostics and the log path.
  • Every run persists its full log behind its ref, so nothing printed is the only copy.
  • The guard denies piping magus output and names -s or -o instead.

Good

A pass, in full:

ref  out2ad91ba6e6f7

Bad

[INFO] Resolving workspace...
[INFO] Found 214 projects
[INFO] Hashing inputs for docs (1/214)
...
[INFO] Done in 4.2s. 214 succeeded, 0 failed.

Two hundred lines to say nothing went wrong. A person stops reading output like this, and an agent carries every line of it to the end of the session.

See also

PrinciplesPages in this section. A record of refusalsCapabilities magus could have had and does not, or had and removed, with what decided each and where to check it. magus queryResolve search terms to knowledge-graph nodes and return the ranked matches plus their neighborhood; also retrieves a target's captured output by ref and a run's journal by invocation id. Target output referencesEvery target that runs gets a short reference id (out1a2b3c) for its captured output. Retrieve any target's exact output later with magus query, pipe it anywhere, or open it in the browser log viewer, no copy-pasting a wall of text.
designprincipleclioutput
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.

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.

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.

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.

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.

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.

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.

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.