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-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(1), magus-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-shell(1), magus-vcs(1), magus-queue(1), magus-doctor(1), magus-config(1), magus-session(1), magus-job(1), magus-notes(1), magus-diff(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-spell(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. magus describeDefine a magus concept (spell, charm, target, project, workspace, module, mcp-tool, tool, file, graph, harness) and list every entity of that kind, or detail one when a name is given. DoctrineThe standing design decisions: the principles magus is built by, the standard it is measured against, and the line between what it automates and what it leaves to your judgment.
generatedinternal/cli/registry.goclimagus agentskillsagentsAGENTS.mdinstallharness
Last updated (479ce5c7)
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. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Affected

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

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. See server.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

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. See knowledge.

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.

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.

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 server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

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.

Conventions

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