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

magus-insight

Behavioral code analysis from VCS and run-outcome history

Synopsis

magus insight <lens> [flags]

Description

Read history to show where a codebase's attention and risk concentrate. Four lenses read version-control history; a fifth, volatility, reads run-outcome history instead. The VCS lenses are contextual to the working directory by default - run from inside a subtree and each reflects only that subtree's history; pass --workspace to analyze the whole workspace (the fan-in postflight uses this). The active VCS adapter must report per-commit files (git can).

VCS-history lenses (the first argument):

hotspots Edit frequency x complexity - the prime refactoring targets. The project view is the dependency graph heat-colored by churn (with authors, recency, blast radius, and CI duration); --files ranks individual files by churn x complexity. affinity Projects that change together (temporal coupling). A hidden pair co-changes without either declaring a dependency on the other - a candidate architectural smell. ownership Author concentration: the primary author and their share, distinct author count (bus factor), and abandonment (projects gone quiet). trend The recent half of the window versus the earlier half: a positive delta is a rising hotspot, a negative one is cooling.

Run-outcome lens:

volatility Each (project, target) pair's recent pass/fail/volatile record scored by its Wilson lower bound; a pair at or above the configured threshold is flagged volatile - a flakiness signal, the prime stabilization targets. It reads the shared runtime-history file, not git, so it takes no --commits/--since window and is always workspace-wide.

report Every lens plus graph stats as one whole-workspace Markdown document. With --mermaid-style=safe the Mermaid subset is restricted to what older or partial renderers (GitHub step summaries, blog renderers) reliably handle; the default "standard" emits the full Mermaid spec for tools that render it. The magusfile's postflight target prints this to stdout for local use.

The VCS lenses read the commit log: --commits caps the scan; --since bounds it by date (90d, 12w, 6mo, 1y). Each lens accepts -o text|json|yaml|name; hotspots and affinity also render -o mermaid (the hotspots file view renders a churn-vs-complexity quadrant). The structural companion - god nodes, orphans, and doc coverage from the knowledge graph - is magus graph stats; the report embeds it.

Options

--commits int (default: 500)
Cap on how many recent commits to scan (VCS lenses only)
--files
hotspots: rank individual files instead of projects
--since string
Only commits within this window, e.g. 90d, 12w, 6mo, 1y (VCS lenses only)
--workspace
Analyze the whole workspace instead of the current project/subtree

Examples

Prime refactoring targets (files)

magus insight hotspots --files

Churn-vs-complexity quadrant

magus insight hotspots --files -o mermaid

Hidden architectural coupling

magus insight affinity

Bus factor and abandonment

magus insight ownership

Rising vs cooling activity

magus insight trend --since 90d

Flaky (volatile) targets

magus insight volatility

Whole-workspace report (all lenses)

magus insight report --workspace

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-watch(1), magus-status(1), magus-doctor(1), magus-config(1), magus-server(1), magus-completion(1), magus-man(1), magus-init(1), magus-self(1), magus-version(1)

ManpagePages in this section. The CLI in practiceThe magus subcommands you actually reach for, grouped by the question you are asking, with the quirks that are not obvious from the help text. MCPThe magus daemon exposes a Model Context Protocol server over Streamable HTTP so AI agents and IDE plugins can call build tools directly. InsightHow magus reads VCS history to show where a codebase's attention and risk concentrate - hotspots, temporal coupling, ownership, and trend - as a behavioral complement to static structure.
auto-generatedclimagus insightanalysishotspotsownershipcouplingvcsvolatilityflaky
Last updated (a103255f)
Earlier changes on this page (4)

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.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

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.

Affected

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

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.

Volatility

A target that fails once and passes on rerun is volatile, as opposed to a regression that started failing and stays failing. magus keeps per-target pass/fail history and a Wilson-score volatility rate to tell them apart and auto-retry the noise. See volatility.

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

Conventions

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