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

magus-notes

Human-authored notes committed to the repository

Synopsis

magus notes <ls|get|edit|verify|capture> [flags]

Description

Read the workspace's human-authored notes.

A note carries knowledge whose only provenance is a person: something no extractor could derive from the tree, and that no rebuild would recover. That is what separates it from the two things it is NOT. Documentation describes the system for a reader and lives in the docs tree. A NOTE/WHY/TODO comment marks one location in one file. A note attaches to graph ENTITIES - a symbol, a file, a project, a target, another note - and may span several at once, which is how it can record something like "these two caches must be invalidated together" that no single comment could hold.

Anchors are required, and they name node IDs rather than positions. A symbol anchor survives the code moving file and line and breaks only on a rename or a deletion, which is exactly when the note should be re-read; a line number would break on the next edit above it with nothing to detect.

There is no put. Notes are written by a person in their own editor and committed under their own name, which is what makes git attribution meaningful and what keeps the store worth trusting. Set knowledge.notes.path in magus.yaml to declare where they live; with nothing declared the feature is inert.

notes ls options

--private
Only your own notes
--reproducible
Omit values that are real but unstable (file mtimes, absolute paths), so the output can be committed
--shared
Only notes committed to this repository (your team has these)
--tag string
Only notes carrying this tag; repeatable, a note must carry every one (gap/open lists open gaps)

notes capture options

--anchor string
With --gap, what the gap is about (repeatable): symbol:<key>, file:<path>#<decl>, diagnostic:<code>, or any note anchor
--gap
Capture a harness gap: positional arguments are the refs it was seen in, and every --anchor must resolve
--name string
Note name (defaults to review-<patch digest>)
--private
Only your own notes (default for capture)
--shared
Only notes committed to this repository (your team has these)
--tag string
Tag to set on the note; repeatable
--title string
Title for the note (defaults to naming the reviewed base)

Subcommands

ls
Show notes and any repair warnings
get
Show one note
edit
Open one note in $VISUAL or $EDITOR
verify
Check malformed notes and anchors that no longer resolve
capture
Capture the review under way as a note: your own remarks plus any colleagues' comments

Examples

List every note

magus notes ls

Read one note

magus notes get cache-invalidation-pairing

Write or revise one

magus notes edit cache-invalidation-pairing

Check every anchor still resolves

magus notes verify

Capture the review under way

magus notes capture

Record a harness gap that magus can find again

magus notes capture --gap --shared --title "wait poll denied as sleep" --anchor diagnostic:MGS3009 grd6392b52c2ea13c5a

List open gaps with their find lines

magus notes ls --tag gap/open

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-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-agent(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. 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. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect.
generatedinternal/commands/registry.goclimagus notesnotesknowledgeannotations
Last updated (61fd39a7)
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. Workspace in full.

Project

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

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

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache 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.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Span

OpenTelemetry's name for one unit of work under a trace: a target execution, whose sub-operations are child spans. An output reference points at a span's captured output. Span 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.

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.

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.

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.