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

Determinism at chosen points

A harness is the deterministic part of the work on a change, for a person or an agent (A harness is not an agent thing). Around a model's agent loop it is the checks, permission gates, typed contracts, leases, graph-backed answers and hooks. It comes in degrees. With no harness, the model judges every step, including the ones that have a right answer: is this path a generated output, does another job own this file, did the check pass. A harness that decides every step leaves the model nothing to judge, and judgment is the reason to run one. magus is built for the hybrid between those two ends.

magus fixes a step where it can prove the answer and leaves the rest to the model. The guard allows or denies an action from declared outputs, leases and VCS state. A job lease fixes the write paths and the check. A spell's typed contract fixes what it takes and returns. magus query, explain and refs answer from the graph. Between those points the model reads, plans and writes the way it chooses. magus supplies facts and verdicts, never the plan, and the prompt stays the host's and the person's. Skills and MAGUS.md are reference text an agent loads when a task calls for it. Which steps are fixed is a human in the loop decision: a person writes the guard rule, forks the job, declares the outputs, and reviews each in version control.

A harness that does more than that starts to own the loop. It rewrites prompts, sequences tool calls, or tunes its text to one model's habits. Each of those couples it to one LLM provider. Providers change tool names, context loading and model behavior on their own schedule, so a harness tuned to one model overfits to it and has to be tuned again for the next model or the next host. magus steers away from that on purpose. One guard, one lease store and one graph serve every host magus wires.

The layers, from the inside out:

  1. The model, which proposes the next action.
  2. The host's agent loop (Claude Code, Codex, Cursor, OpenCode), which sends context to the model and runs the tool calls it returns.
  3. The harness magus supplies: guard hooks, skills, MCP tools and job leases, attached at the host's hook points.
  4. magus's deterministic workspace model: the project graph, each target's inputs and outputs, the cache and the job store, which the harness reads.

Layers 2 and 3 are the ones most often merged under one name. magus keeps them apart: the host owns the loop, and magus owns what the loop can ask and what it is refused.

Enforced by

  • Verdicts read facts no model produces: declared outputs, leases, VCS state.
  • The hook contract is keyed by field rather than host name, which the hostagnostic and hostvocab linters enforce.
  • magus builds no model adapter and no agent loop (A record of refusals).

Good

A fact with a right answer comes from the graph, and the model spends its turn on the part that needs judgment:

magus describe file docs/MAGUS.md -o json

Bad

system: Before each edit, call tools in this order: plan, search, read, edit, test.
Use at most 3 searches. Prefer the Read tool over Bash.

The harness has taken over the plan and tuned it to one host's tool names, so it has to be rewritten for the next model and the next host.

See also

JudgmentPages 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. AgentsHow magus equips AI agents (the installable skills, the MAGUS.md routing index, the MCP server, and the guard hook any agent host can wire), with a setup page per host. 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.
designjudgmentagentsharness
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.

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.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache 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.

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.

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.

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.

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.

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.

Conventions

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