magus v0.4.3 is out. See what's new
¶ View generated markdown
3 min read

magus-agent

Manage skills, harnesses, and agent feedback

Synopsis

magus agent <install|harness|starter|adoption> [flags]

Description

Render the agent skills embedded in this binary and write or stream them into named destinations (<skills-dir>).

magus never writes your AGENTS.md. That file is yours, and an installer that edits a file you own leaves bytes you did not write and cannot audit. So install PRINTS the managed magus block for you to paste, and only when your AGENTS.md is missing it or is carrying a stale one. sample prints a starter AGENTS.md to stdout for you to own and tweak, and never writes a file.

harness installs the skill trees of, or verifies, harnesses selected with magus\harness.provider (several hosts are fine when you bounce between LLM tools): verify actually runs the wired guard command against a synthetic event rather than trusting its mere presence in the config. The host config is yours for the same reason AGENTS.md is: magus describe harness prints the entries it needs and the one command that merges them, and you run it. Omit --id to act on every magusfile-wired provider. Guard feedback that keeps recurring is doctor's recurring-guard-denials check, not a verb here.

agent is a pure data generator, which is what makes --tar the general answer: it streams a tar archive to stdout, so skills can be installed anywhere a shell can reach. The write-to-disk form exists for the in-repo, paths-relative-to-<dir> case. Absolute destinations are refused unless --global is set, so magus cannot silently write outside the working tree.

adoption reads shell commands, one per line, from stdin or from --commands <file>, and reports how often the graph was reached versus a raw text search. -o json emits the report as one object keyed total, graph_verbs, text_searches, search_of_source, search_of_prose, file_reads, magus_runs, other, and top_symbol_greps. Each top_symbol_greps entry carries pattern, count, and run - the graph command to try for that pattern, routed by its shape: magus query for a diagnostic code or a Buzz op, which magus refs (compiled-language symbols only) would miss, and magus refs otherwise. The text report prints the same command after each pattern, and run is empty for a pattern no graph verb fits.

Options

--dir string (default: .)
Repo directory to install into (agent install)
--dry-run
Print what would be written and removed without touching the filesystem (agent install)
--force
Overwrite existing installed skill files (agent install)
--global
Allow absolute destination paths in write mode (agent install)
--skill-form string (default: both)
Skill form to install: both (default), short, or full (agent install)
--tar
Stream a tar archive to stdout instead of writing files (agent install)

agent harness verify options

--id string
Harness ID; omit to verify every magusfile-wired provider

agent harness install options

--id string
Harness ID; omit to install every magusfile-wired provider

agent adoption options

--commands string
File of shell commands, one per line; without it commands are read from stdin

Subcommands

install
Render the embedded skills and write or stream them into named destinations
harness
Install skills for, or verify, harnesses wired in the magusfile
starter
Print a starter AGENTS.md to stdout; never writes a file
adoption
Report how often agents used the knowledge graph versus a raw text search

Examples

Install into a repository's agent skills directory

magus agent install .agents/skills

Refresh installed skills

magus agent install .agents/skills --force

See what an install would write and remove first

magus agent install .agents/skills --force --dry-run

Install anywhere via tar

magus agent install --tar | tar -xf - -C .agents/skills

Print a starter AGENTS.md

magus agent starter

Measure graph adoption from shell commands

magus agent adoption --commands commands.txt

Read commands from stdin

magus agent adoption < commands.txt

The report as JSON, for a dashboard

magus agent adoption --commands commands.txt -o json

See Also

magus(1), magus-ls(1), magus-describe(1), magus-where(1), magus-run(1), magus-affected(1), magus-x(1), magus-clean(1), magus-shell(1), magus-query(1), magus-refs(1), magus-explain(1), magus-path(1), magus-graph(1), magus-diff(1), magus-vcs(1), magus-session(1), magus-job(1), magus-notes(1), magus-queue(1), magus-watch(1), magus-events(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-status(1), magus-buzz(1), magus-spell(1), magus-init(1), magus-doctor(1), magus-config(1), magus-completion(1), magus-man(1), magus-self(1), magus-version(1)

ManpagePages 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. The guardWhat magus session hook denies, what it only notes, and why: the five deny grounds, how a workspace sets a built-in rule, the file-write rules, the verdict contract a host wires into, and the observations magus records. MCPmagus serves its tools as a Model Context Protocol server, over stdio for the agent host that launches magus mcp, or over Streamable HTTP from magus server.
generatedinternal/commands/registry.goclimagus agentskillsagentsAGENTS.mdinstallharness
Last updated (29d8b3de)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. Magusfile 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.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. Affected in full.

Broker

The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. Broker in full.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. Knowledge graph 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.

Diagnostic code

A stable MGSxxxx identifier attached to a magus warning or error, so it can be referenced and looked up; some are guardrails (see wards), others hard errors. Diagnostic code 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.

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.

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.

Conventions

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