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, andmagent-agent-shell-ask-at-pointfor free-form requests rather than a predefined workflow.