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

magus-session

What magus invocations did and what agents are blocked on: humans read and dispose, hosts write

Synopsis

magus session [ls] [flags]

Description

One noun over the repository's session store, with a human side and a machine side.

Humans read it. The bare command lists past magus invocations with the targets each one ran and how those runs ended, the OS user that ran it, and the host session it ran in (a dash when no host delivered one: the invocation is unattributed); `session attention` lists the requests agents have raised - work blocked on input or on approval - and `session dispose` closes one. Nothing closes a request automatically: there is no expiry, no severity inference and no auto-dispose flag, because a request magus could answer by itself would not have needed a person - see the doctrine page.

Agent hosts write it. Their hooks pipe every judged command through `magus shell`, which records what it judged, and every attention event through `session notify` (normalized; a waiting or permission outcome opens a durable request). No person types notify; it exists to be wired. `magus shell` is the exception, and deliberately so: it is the same command a person runs to ask what this workspace would rather they ran.

The store is keyed by repository identity rather than by checkout path, so every git worktree of one repo reads and writes the same records - what another worktree just finished, and what it is blocked on, is visible here without a server, a network, or a shared branch. It is append-only and never rewritten; a line left half-written by a killed process is skipped and counted rather than failing the read.

The listing takes --limit to bound by count and --since to bound by AGE, as a duration back from now (2h, 45m, 168h) or an RFC3339 instant. --since compares against each invocation's last fact, not its first, so a long one that is still working stays listed however long ago it began.

--brief answers the listing's own question, where does the work stand, for a model instead of a person. It prints this checkout read off disk: branch and revision, commits not yet on the base ref, the dirty tree split by the classifier `magus describe file` uses, the live leases with the command that binds each one, the last recorded run's failures with the ref that holds their output, whether any host hook config here invokes magus, and where this workspace's rules live. Nothing in it is remembered: an agent host that replaces a session's history with a summary can wire this to its session-start event and hand the model state instead of prose.

Options

--brief
Print this checkout's state for a session that lost its history: revision, unpushed commits, classified dirty tree, live leases, the last run's failures, guard wiring (--limit and --since do not apply)
--limit int
Show at most this many invocations (0 for all)
--since string
Show only invocations active since this point: a duration back from now (2h, 45m, 168h) or an RFC3339 timestamp

session load options

--file string
Read the event stream from this file instead of stdin

session dispose options

--reason string
Record why the request is being closed, alongside the disposition

session checkpoint options

--agent-name string
Name of the agent host this session ran on, when one did (attribution only)
--note string
A sentence on where the work stands
--session string
The host's own session id for this session
--transcript string
Path to the host's own log of this session, recorded as a pointer; magus never opens it

session notify options

--desktop
Also raise an OS notification
--outcome string
Outcome vocabulary for the event

Subcommands

ls
List past magus invocations and the targets they ran (the default)
load
Load a normalized agent-session event stream from a host transcript
show
Report one loaded session: what it ran, what the rules say, what it loaded
hints
Report uptake per hint id: served, followed, rejected, reflex
attention
List the open requests agents raised, oldest first; with -q, print nothing and exit 1 when the queue is empty
dispose
Close one open request by id or unambiguous id prefix
checkpoint
Record where the work stands, so it can be picked up later
notify
Normalize an attention event and optionally notify the local desktop

Exit status

0
Sessions or requests were listed, a request was disposed, or an event was normalized and emitted. A plain listing exits 0 whether or not anything was listed, because an empty queue is the good state. notify's delivery is best-effort and never changes this: a desktop notification that could not be raised, and a durable request that could not be opened, are both reported as warnings and still exit 0.
1
dispose: the request named is not in the store, or was already disposed; a request closes once and stays closed. attention with -q: the queue is empty, so a prompt or watch loop can branch on status instead of parsing the listing. notify: stdin could not be read. Text that is not a complete event envelope becomes the event's message rather than an error. load: at least one line was rejected; usable lines are still loaded and the summary is printed, so fix the adapter and run it again. show: the session named has no loaded events.
2
Misuse: an unknown subcommand, an argument to a listing, or a dispose naming other than exactly one id.

Examples

Show recent invocations

magus session

Show today's work

magus session --since 24h

Hand a compacted session this checkout's state

magus session --brief

Full session records as JSON

magus session -o json

Load a host transcript an adapter normalized

magus session load --file events.ndjson

Read one loaded session back

magus session show 8f1c2d4e

List open attention requests

magus session attention

Ask whether anyone is waiting

magus session attention -q

Close one request, saying why

magus session dispose att-3f9c -reason "approved and pushed by hand"

Raise a permission prompt on the desktop (host-wired)

printf '%s\n' 'needs approval' | magus session notify --outcome permission --desktop

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-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. magus brokerCheck or stop the broker: the per-user process that holds this host's concurrency slots, declared memory and shared services, which a run starts on its own. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect.
generatedinternal/cli/registry.goclimagus sessionsessionsattentionhistoryworktreesagentsguard
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.

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.

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.

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.

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.

Invocation

One magus process's recorded facts - the targets it finished, their outcomes, the lease it acted as, and the session it ran in when a host delivered one - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Attention request

A durable "an agent is blocked" record, opened when a magus session notify event carries the waiting or permission outcome and held until a person disposes it. magus session attention lists what is open. Nothing closes one on its own - see doctrine.

Dispose

The human act of closing an attention request: a judgment rendered, recorded with who and why. Distinct from resolving a review thread or a merge conflict - a disposition answers a request; it does not merge anything.

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.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

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