M Magent eMacs-native LLM AGENT

Commands And LLM Workflows

Magent has two distinct command surfaces for LLM-assisted workflows:

  • Slash commands run reusable instruction skills or session controls in the current agent-shell conversation.
  • Internal workflow commands are explicit Emacs commands that run Magent maintenance or diagnostic work in isolated durable sessions.

The bundled package currently provides eight slash commands (six skill commands and two session controls) and four internal workflow commands. Four additional Emacs commands inspect or manage the internal workflows.

Slash Commands

Type a slash command as the prompt in the Magent agent-shell buffer:

/review
/summarize src/session persistence and replay
/fix focus on the failing session persistence test
/compact preserve exact filenames and remaining failures
/clear

Text following a skill command or /compact is appended as an additional instruction. Skill commands use the current session and agent and attach the corresponding instruction skill to that request. An unknown slash command is submitted as ordinary prompt text rather than executed locally.

Command Purpose Expected effect
/explain Explain code, a diff, error, or context Read-only inspection; does not edit files
/fix Diagnose and repair a bug or regression May edit files and run focused verification
/init Create or refresh project AGENTS.md May update project instructions after repository inspection
/review Review current changes for defects Read-only review; leads with findings and test gaps
/summarize Summarize the project into org-roam Creates or updates one canonical Org note
/test Run and interpret relevant tests Runs focused tests; may fix an in-scope failure when appropriate
/compact Summarize the current conversation Replaces older model context with a continuation summary
/clear Clear the current conversation Cancels pending work and removes live and persisted session context

/compact

Uses the hidden, tool-free compaction agent to produce a continuation summary. After it succeeds, future turns reuse that summary instead of the older model context. The visible transcript remains available in the current agent-shell buffer. A failed compaction leaves the previous context unchanged.

/clear

Cancels active or queued work for the current runtime session, clears its messages, tools, child jobs, approvals, selected one-shot skills, and persisted transcript, while keeping the agent-shell session handle valid. It does not accept an argument.

/explain

Inspects the relevant buffer, region, file, diff, error, or project context and explains the entry points, data flow, state changes, and ownership boundaries. It is intended for understanding existing behavior and does not make edits.

/explain why this callback can complete twice

/fix

Reconstructs the symptom, identifies the smallest plausible root cause, makes a focused change, adds or updates a regression test when practical, and runs the verification that should catch the problem.

/fix reproduce and repair the failing ledger replay test

/init

Inspects repository documentation, manifests, tests, and workflows, then creates or refreshes the project-root AGENTS.md. Useful existing instructions are preserved and unrelated churn should be avoided.

/init include the live Emacs verification workflow

/review

Reviews the current repository state and diff like a senior code reviewer. It prioritizes correctness bugs, regressions, unsafe edge cases, and missing tests, with findings ordered by severity. It does not edit files unless explicitly asked.

/review focus on cancellation and stale callbacks

/test

Finds the relevant project test command, starts with the narrowest meaningful test, and broadens only when useful. The result records passed, failed, and skipped checks plus remaining risk.

/test run the focused tests for the files changed in this branch

/summarize

Inspects the current Git project and writes a single org-roam note whose title is exactly the repository name. With no argument it updates * Repository Summary for the whole workspace. Trailing free-form text selects a path or semantic scope and upserts one subtree under * Scoped Summaries in the same file. Global sessions are rejected before an LLM turn is created.

The destination is magent-org-roam-directory, or org-roam-directory when the Magent option is nil. The directory must already exist. The writer owns the Org ID, repository path, analyzed Git commit, filename, and atomic update. New notes are created through the noninteractive Org-roam capture API when it is available; the canonical file-level property drawer always precedes Org keywords so Org-roam can recognize and index the node. New filenames follow YYYY-MM-DDtHHMM.org, matching the default Org-roam capture convention. Subsequent runs locate the note by its file-level REPO_PATH, so timestamped, legacy, and manually renamed files still receive single-file updates.

/summarize
/summarize only the ACP session lifecycle
/summarize lisp/magent-session.el

Alternate Invocation And Extension

M-x magent-agent-shell-run-skill-command selects and runs any command-like instruction skill through the supported agent-shell frontend.

The skill-backed portion of the slash command list is extensible. Any loaded instruction skill with a default-prompt field is advertised to agent-shell as a slash command. Skills can come from bundled skills/, the user skill directories, or project-local .magent/skills/ overlays. Therefore a local installation can expose more skill commands in addition to the two fixed session controls listed above.

User Skill Management

M-x magent-skill-find searches skills.sh and displays the ten most-installed matches in a dedicated buffer. Press RET to preview the selected candidate, i to install it directly, or g to run another search. There is no need to copy a repository name from the finder.

M-x magent-skill-install also accepts one local skill directory, owner/repo@skill, or a public GitHub URL. Before writing, Magent shows the source, commit when available, description, destination, file count, size, and whether the package contains scripts or code. Installation proceeds after one y/n confirmation, copies files without executing scripts, accepts instruction skills only, and records .magent-install.json provenance. Same-source managed skills can be atomically reinstalled; unmanaged or different-source collisions must be deleted first.

M-x magent-skill-delete permanently removes one selected user-level skill after one y/n confirmation. It can remove managed and unmanaged user skills; a symbolic-link entry removes only the link. The manager uses Magent’s user skill directories (normally ~/.emacs.d/magent/skills/) and never manages project-local .magent/skills/ or ~/.agents/skills/.

Internal Workflow Commands

Internal workflows are invoked through M-x and are intentionally not exposed as agent-shell slash commands. Every run gets an isolated session under magent-session-directory/internal and records only a compact breadcrumb in the originating conversation.

Emacs command Workflow LLM behavior
magent-run-memory-init Build initial Emacs profile memory Uses the current gptel provider when magent-memory-use-llm is non-nil
magent-run-memory-refresh Refresh managed profile memory Uses the current gptel provider when magent-memory-use-llm is non-nil
magent-run-memory-clear Deactivate and clear managed memory Local operation; does not request an LLM summary
magent-run-doctor Diagnose Magent and current runtime state Sends one sanitized, tool-free analysis request

Memory Initialization And Refresh

M-x magent-run-memory-init discovers bounded Emacs configuration sources, shows a scan plan for approval, and writes the managed profile memory file. M-x magent-run-memory-refresh repeats the scan while preserving user notes.

By default, init and refresh summarize sanitized source excerpts with the current gptel provider. Customize magent-memory-use-llm to nil to write a deterministic skeleton and source index without sending configuration excerpts to the provider.

Memory Clear

M-x magent-run-memory-clear deactivates the managed profile and clears its generated content after confirmation. User notes and a snapshot are retained. This workflow does not perform an LLM summarization request.

Doctor

M-x magent-run-doctor collects bounded evidence through trusted read-only probes, recursively redacts it, and sends one request without model tools. With a prefix argument, C-u M-x magent-run-doctor lets the user review applicable probe selection. See DOCTOR.org for the probe API and security boundary.

Inspecting And Managing Workflows

Emacs command Purpose
magent-list-internal-sessions Select a saved internal session and inspect its final result and activity
magent-cancel-internal-command Cancel an active internal workflow that exposes cancellation
magent-memory-open Open the managed Emacs profile memory file
magent-memory-status Show whether memory exists, is active, or appears stale

Internal session viewers show the final result first and keep detailed activity collapsed by default. Cancellation is session-scoped and does not cancel work belonging to unrelated Magent conversations.

Choosing The Right Surface

  • Use a slash command when the task belongs to the current coding conversation and should reuse its agent, context, and transcript.
  • Use an internal workflow command for Magent-owned maintenance, profile-memory management, or sanitized diagnosis that needs its own durable session.
  • Use magent-agent-shell-dwim, magent-agent-shell-prompt-region, and magent-agent-shell-ask-at-point for free-form requests rather than a predefined workflow.