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

magus-graph

The workspace's graphs as objects: deps, export, stats

Synopsis

magus graph <build|push|pull|deps|export|stats|diff> [flags]

Description

The workspace's graphs as objects: emit, export, and measure them. The query, explain, and path verbs read the knowledge graph; magus graph is the home of the graph itself.

Subcommands (the first argument):

build Rebuild the knowledge graph now, reindexing code symbols first (runs each symbol-capable project's scip op) unless --no-symbols, then running each adapter declared in knowledge.sessions unless --no-sessions. The server does this automatically in the background; this is the manual trigger, after a branch switch or when the server is not running. deps The project dependency DAG. A trailing list of project paths roots the graph; -o selects text, json, yaml, dot, mermaid, or tree. The same view scoped to a run is available as magus run <target> --graph and magus affected <target> --graph. export The merged knowledge graph: the deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, methods, diagnostics, docs, buzz sources). -o json emits the node-link form; -o graphml emits GraphML. External graph viewers (Gephi, yEd) read both directly. --select "<terms>" narrows the export to a query's neighborhood (same engine as magus query); -o dot and -o mermaid render only with --select, since the full graph has too many nodes to lay out. The graph is cache-backed under <cache>/knowledge; only shards whose sources changed are rebuilt. --open sends it to the hosted, interactive Graph Explorer instead of stdout (there is no separate "open" subcommand): by default the graph rides in the URL fragment (#data=...), which browsers never send to a server; --serve instead hands it from an ephemeral 127.0.0.1 loopback server (no size limit), and --targets opens the target dependency graph instead of the knowledge graph. stats The graph's shape: god nodes (the most connected spells, modules, targets - where structural risk concentrates), orphans (docs that document nothing, spells no target uses), and doc coverage (the share of diagnostics, spells, and modules with a doc). --kind scopes every section to one node kind. The VCS-history lenses (hotspots, affinity, ownership, trend, unreferenced) are a separate view, served by the magus_insight MCP tool and the console's Insight page - not by this command. diff Nodes and edges added, removed, or changed relative to a baseline export or a git revision (--rev): the PR-review blast-radius artifact, emit as json or markdown for a CI comment.

graph build options

--no-sessions
Do not run the declared agent-session adapters first
--no-symbols
Rebuild the domain graph only; do not reindex code symbols

graph push options

--ref string
The artifact to push to, as <registry>/<repository>:<tag> (required; never derived)
--refresh
Rebuild the graph before pushing instead of exporting what is cached
--username string
The registry username; the token is read from stdin, the way docker login --password-stdin takes one

graph pull options

--out string
Write the graph here instead of stdout
--ref string
The artifact to pull (default: derived from the repository's origin remote)

graph deps options

--depth int
Cap displayed depth (0 = unlimited)
--spell string
Only projects driven by this spell
--target string
Target whose duration history annotates nodes (default: build)
--upstream
Show dependents instead of dependencies

graph export options

--budget int (default: 50)
Node budget for --select (how many nodes the neighborhood may collect)
--follow
With --open: keep the explorer updating from the running server instead of showing a snapshot (needs magus server start)
--global
Union the workspaces registered in config (knowledge.workspaces); node IDs are namespaced by workspace
--open
Deliver the graph to the hosted Graph Explorer instead of stdout; it never leaves your machine
--print
With --open: print the explorer URL to stdout instead of launching a browser
--refresh
Force a full graph rebuild before exporting
--reproducible
Omit everything that is not a function of the source tree (locally observed runtime attrs, git history), so two checkouts of one commit export identical bytes
--select string
Export only the neighborhood of a query (same grammar as magus query); required for -o dot and -o mermaid
--serve
With --open: hand the graph to the page from an ephemeral loopback server instead of a URL fragment (no size limit; incompatible with --targets)
--static
Deprecated alias for --reproducible
--symbols magus diff --baseline
Include every indexed code symbol, which the whole-graph export leaves out; a `magus diff --baseline` needs them
--targets
With --open: open the target dependency graph instead of the knowledge graph; pass a project path to scope it
--url string (default: https://eli.gladman.cc/magus/console/graph/)
With --open: base URL of the Graph Explorer page (override for a self-hosted mirror)

graph stats options

--global
Union the workspaces registered in config (knowledge.workspaces) before computing stats
--kind string
Scope every section to one node kind (spell, target, doc, ...)
--refresh
Force a full graph rebuild first
--symbols
Include the lazily-loaded symbol shards in the stats; excluded by default because they can dwarf the domain graph

graph diff options

--global
Diff the global (all-workspaces) graph; match this to how the baseline was exported
--refresh
Force a full graph rebuild of the current graph before diffing
--rev string
Diff against a git revision (e.g. HEAD~1, main) instead of an export file

Subcommands

build
Rebuild the knowledge graph now, reindexing code symbols first
push
Push the knowledge graph to a container registry as an OCI artifact
pull
Fetch a published knowledge graph; reads public artifacts with no credentials
deps
Emit the project dependency DAG (text, json, yaml, dot, mermaid, tree)
export
Export the merged knowledge graph (json node-link or graphml)
stats
Report the knowledge graph's shape: god nodes, orphans, doc coverage
diff
Nodes/edges added, removed, or changed vs a baseline export or --rev; PR blast-radius

Examples

Project DAG as Mermaid

magus graph deps -o mermaid

DAG rooted at one project, dependents up

magus graph deps pkg/api --upstream

Knowledge graph for an external viewer

magus graph export -o json > graph.json

GraphML for Gephi or yEd

magus graph export -o graphml > graph.graphml

A query's neighborhood as Mermaid

magus graph export --select 'kind=spell go' -o mermaid

Where structural risk concentrates

magus graph stats

Doc coverage for spells only

magus graph stats --kind spell

Open knowledge graph in browser

magus graph export --open

Open target dependency graph

magus graph export --open --targets

Scope target graph to one project

magus graph export --open --targets docs

Print the URL instead of opening

magus graph export --open --targets --print

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(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-agent(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. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain - projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources - that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export. 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 graphgraphknowledge graphdependency graphexportgraphml
Last updated (95680f58)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

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

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

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

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

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.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Snapshot

A point-in-time view of live state - the pool's occupancy or a tick of exported metrics - as opposed to accumulated history. 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.

Insight

The reports magus derives over the graph and history (hotspots, affinity, ownership, trend, volatility, unreferenced). See insight.

Hotspot

An insight lens: edit frequency times complexity, the prime refactoring targets. The project view heat-colors the dependency graph by churn; --files ranks individual files. See insight.

Affinity

An insight lens: projects that change together (temporal coupling). A pair that co-changes without either declaring a dependency on the other is a candidate architectural smell. See insight.

Ownership

An insight lens: author concentration - the primary author and their share, the distinct-author count (the bus factor), and abandonment. See insight.

Trend

An insight lens: the recent half of the window against the earlier half. A positive delta is a rising hotspot; a negative one is cooling. See insight.

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.