magus v0.4.3 is out. See what's new
¶ View generated markdown
4 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 applies, removes, or verifies harnesses selected with magus\harness.provider (several hosts are fine when you bounce between LLM tools): apply merges opaque host-config fragments the descriptor already names, remove deletes only those same fragments (a user's own hooks beside them are untouched, and nothing is asked for confirmation - pass --dry-run to preview one first), and verify actually runs the wired guard command against a synthetic event rather than trusting its mere presence in the config. 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)
--prune
Also remove installed skills this binary no longer ships; without it they are reported and left in place, and only skills magus wrote are ever candidates (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 apply options

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

agent harness remove options

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

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
Apply, remove, 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

Refresh, and drop skills this version no longer ships

magus agent install .agents/skills --force --prune

See what a prune would remove first

magus agent install .agents/skills --prune --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-memory(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) and list every entity of that kind, or detail one when a name is given. 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/cli/registry.goclimagus agentskillsagentsAGENTS.mdinstallharness
Last updated (00e25f0e)
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.