<!-- Generated by community/.ai/render-guides.mjs; edit community/.agents/skills/modcommand-migration/SKILL.md -->

Migrating quick-fixes and intentions to the ModCommand API

Two APIs coexist in this repo, and they are not two styles of the same thing — they have opposite execution models:

	LocalQuickFix / IntentionAction	ModCommandQuickFix / ModCommandAction
when it runs	write action on EDT	background read action
what it does	mutates physical PSI directly	returns a ModCommand describing the effect; something else executes it
PSI it sees	physical	non-physical copies
capability	anything (dialogs, project model, refactoring engines, Editor)	only what the sealed ModCommand hierarchy models
intention preview	hand-written	derived from the returned command

So this is not a mechanical rename. A ModCommandQuickFix cannot show arbitrary UI, and it has no Editor. That constraint is the whole point: because the command is a declarative, serializable record, non-IDE clients can execute it.

Why bother: no write action on EDT means no freeze/slow-op report from the action; preview comes for free; and it is a hard requirement for clients that only speak ModCommand — LSP code actions accept only ModCommandQuickFix (LSP-670), Next Edit Suggestions only ModCommandAction (SCL-21364), plus Qodana and Fleet.

Step 1 — Triage before you touch anything

Not every fix can be converted. Decide this first. Read the fix's applyFix/invoke body and everything it calls, and sort it into one of three buckets.

Convert directly

Everything it does is PSI editing plus editor state that ModPsiUpdater models:

• edits PSI in its own file, or in several files
• moves the caret, changes the selection, adds highlighting
• starts a live template
• starts the standard Rename UI — replace direct VariableInplaceRenamer or PsiElementRenameHandler.invoke calls with updater.rename. The executor delegates to registered Renamers, so the result may be an inline rename or a rename dialog depending on the symbol, language, and context
• shows an information/error message
• changes an inspection option

Convert, but rewrite the UI

The fix shows UI, but the UI is only picking something. These have declarative equivalents — and the result is usually shorter than the original, with a working preview:

Original UI	Replacement
popup/list choosing an element or a variant	ModCommand.chooseAction + ModCommand.psiUpdateStep
MemberChooser	ModCommand.chooseMultipleMembers (backed by ModEditOptions)
yes/no or "this will break X, continue?" confirmation	ModCommand.showConflicts with a single conflict
a form editing options	ModEditOptions

Return chooseAction also when the list has zero or one option. The platform handles these cases, see recipe 7 in references/recipes.md.

Do not convert

Leave these as LocalQuickFix. Trying to force them through the ModCommand API wastes a session:

• a custom dialog with input — text fields, trees, checkbox matrices, its own preview pane. The standard Rename UI is the exception because ModStartRename models it explicitly
• project model / Gradle / Maven / SDK / language-level configuration
• refactoring engines without a corresponding ModCommand — SafeDeleteProcessor, full change-signature, extract-method. Standard rename is modeled by ModStartRename; the narrow 'suggested refactoring' case is available via ModPsiUpdater.trackDeclaration
• launching external programs

Optionally give such a fix a reduced ModCommand path for headless clients by implementing LocalQuickFixWithModCommandFallback (community/platform/analysis-api/src/com/intellij/modcommand/LocalQuickFixWithModCommandFallback.java) — getFallbackModCommandAction() may skip the advanced behaviour.

A converted fix almost never needs a custom preview. If you find yourself writing generatePreview, first check whether the auto-generated one is actually wrong.

Step 2 — Pick the target base class

You have	Condition	Convert to
LocalQuickFix	body only needs descriptor.getStartElement() — editing several files is still fine here, via updater.getWritable	PsiUpdateModCommandQuickFix → applyFix(project, element, updater)
LocalQuickFix	needs the whole descriptor, composes commands with andThen, or must showConflicts before editing	ModCommandQuickFix → perform(project, descriptor): ModCommand
LocalQuickFix	stores PsiElement / SmartPsiElementPointer fields	PsiUpdateModCommandAction<E> (see below)
BatchQuickFix		ModCommandBatchQuickFix → perform(project, List<ProblemDescriptor>)
IntentionAction, LocalQuickFixAndIntentionActionOnPsiElement	simple	PsiUpdateModCommandAction<E> → invoke(context, element, updater)
IntentionAction, LocalQuickFixAndIntentionActionOnPsiElement	needs the physical element, or builds the command itself	PsiBasedModCommandAction<E> → perform(context, element)
anything else		raw ModCommandAction

Only the base class choice depends on how the fix is anchored. Nothing in this table restricts you to one file — every psiUpdate-based base gets a ModPsiUpdater, so cross-file edits are available from all of them (recipe 5 in references/recipes.md).

Kotlin plugin has its own bases: KotlinModCommandQuickFix<ELEMENT>, KotlinApplicableModCommandAction, KotlinPsiUpdateModCommandAction.

PsiUpdateModCommandAction<E> has two constructors, and picking the wrong one is a common mistake:

• super(element) — bind to a concrete element (the equivalent of a fix that stored a pointer). The element is passed back to getPresentation/invoke already checked for validity and writability.
• super(SomeElement.class) — find an element of that class under the caret. For registered intentionAction extensions with a no-arg constructor.

Binding to several elements is still your job: keep the extra ones in fields as smart pointers and check their validity yourself.

Register an action as a quick-fix with the builder API, which takes a ModCommandAction directly:

holder.problem(element, message).fix(new MyFix(otherElement)).register();

LocalQuickFix.from(ModCommandAction) is the explicit adapter where you need a LocalQuickFix value. (ModCommandAction.asIntention() is the intention-side counterpart.)

Step 3 — Mechanical edits

1. Change the supertype.
2. Add the new method; move the old body into it.
3. Replace descriptor.getStartElement() with element. descriptor.getPsiElement() needs a check first — it is not a synonym. For a descriptor registered with a start and end element, ProblemDescriptorBase.getPsiElement() returns their common parent, which can be a higher element than getStartElement(). PsiUpdateModCommandQuickFix anchors on getStartElement(), so substituting blindly silently changes which element the fix operates on. If the fix genuinely needs getPsiElement(), extend ModCommandQuickFix instead and call ModCommand.psiUpdate(descriptor.getPsiElement(), ...) yourself.
4. Delete startInWriteAction, getElementToMakeWritable, getFileModifierForPreview, generatePreview, and every @SafeFieldForPreview. They are final or redundant on the new bases.
5. Review branches on isOnTheFly and isPhysical; do not delete them blindly. If isOnTheFly only guards navigation or highlighting, call updater.highlight/moveCaretTo unconditionally — batch execution drops those commands for you. Writable PSI is always non-physical, so remove preview-only physicality branches after keeping the behaviour that should now always run. Preserve or rewrite branches that affect PSI edits, availability, search scope, or other semantics. To test for a synthetic element use instanceof SyntheticElement; for a factory-created one, use element.getContainingFile() instanceof DummyHolder.
6. Presentation:
   • on ModCommandQuickFix / PsiUpdateModCommandQuickFix, getName() and getFamilyName() work as before, and marker interfaces (HighPriorityAction, LowPriorityAction) still apply;
   • on a ModCommandAction, all of it moves into getPresentation(): return null where isAvailable() returned false, otherwise Presentation.of(text) with .withPriority(...) (replacing the marker interfaces), .withFixAllOption(this) (replacing IntentionActionWithFixAllOption), .withHighlighting(...), .withIcon(...). Drop any setText()/myText field — the presentation is computed per context.

Step 4 — Rules inside psiUpdate

Full detail in references/psi-updater.md. The rules that break code most often:

• Every element you get is a non-physical copy. Call updater.getWritable(x) for anything in another file, and get all writable copies before writing anything — getWritable throws IllegalStateException once that file's copy has been modified.
• No write actions. Delete WriteCommandAction, CommandProcessor, preparePsiElementForWrite. The engine handles it. Note this does not extend to PsiDocumentManager.commitDocument — see the document bullet below.
• Do not start your own progress. perform/invoke already runs in a background read action under a progress, so a wrapper like runWriteActionWithCancellableProgressInDispatchThread around a long loop just goes away; keep the cancellation by calling ProgressManager.checkCanceled() in the loop.
• No Editor, FileEditorManager or DataContext. Input comes from ActionContext, output from ModPsiUpdater. For a shared helper that still wants an editor, change its parameter to ModNavigator — call sites with a real editor pass editor.asModNavigator(). See FixDocCommentAction.generateComment(PsiElement, Project, ModNavigator) for a helper already converted this way.
• editor.getDocument() → element.getContainingFile().getFileDocument() (or updater.getDocument()). That document is writable, and raw replaceString/insertString/deleteString on it are legal — the engine listens on it and folds your edits into the resulting ModUpdateFileText. Keep the PsiDocumentManager.commitDocument(doc) that follows: without it the PSI you touch next is stale. See references/psi-updater.md.
• The failure path is updater.cancel(message): it discards the changes and shows an error.
• perform/invoke must be side-effect-free with respect to physical state. It may run for preview, and it may not run at all.

Step 5 — Find more candidates

Search with ijproxy (search_text, search_symbol) and fall back to ./community/tools/rg.cmd when MCP is unavailable. Scope with paths, e.g. paths: ["community/python/"]:

• candidates — implements LocalQuickFix, extends LocalQuickFixOnPsiElement, LocalQuickFixAndIntentionActionOnPsiElement, implements IntentionAction
• already migrated — search_symbol for PsiUpdateModCommandQuickFix, ModCommandQuickFix, PsiUpdateModCommandAction
• red flags that decide the triage — @SafeFieldForPreview, generatePreview, getFileModifierForPreview, WriteCommandAction, showAndGet, DialogWrapper, Editor editor

Testing

A conversion is behaviour-preserving, so the inspection's existing tests are the real check. Run them before the change too, to tell a pre-existing failure from one you introduced: ./tests.cmd --module <module> --test <FQN> (FQN required — simple class names do not match). Then lint_files the files you touched. See the testing skill for discovery.

What breaks specifically because of a ModCommand conversion:

• The action's visible name. LocalQuickFix.from(ModCommandAction) — and therefore holder.problem(...).fix(action) — produces an adapter whose getName() returns getFamilyName(). A fix whose old getName() differed from its family name needs its gold-file action hint updated: // "<expected action text>" "<true|false|ProblemHighlightType>".
• A chooser adds a step. Walk into the ModChooseAction in the hint with |-> between steps, e.g. // "Add 'throws RuntimeException' to method signature|->Change only this method" "true-preview". Each segment is matched against the previous step's child actions; if the action returns no chooser the test fails with "does not produce a chooser". Suffix the state with -preview to also assert the intention preview.
• Preview gold data. Deleting a hand-written generatePreview changes the preview. Confirm the generated one is equivalent before accepting a diff — it legitimately shows more, since it covers every file the command touches plus navigation and messages.
• Batch tests. Navigation, highlighting, ModShowConflicts and ModStartRename are dropped, and the first chooser option is auto-selected. Caret and selection assertions therefore belong in interactive tests; if a batch result changed, check your chooser option order.
• Driving an options chooser. ModEditOptions.applyOptions(Map) is @TestOnly — keys are option bind ids, and it returns the next command, so a chooseMultipleMembers branch is testable without UI.
• Worth asserting once: the fix now works with no editor open, since ModPsiUpdater is always available where the old code returned early.

Hint parsing lives in community/platform/testFramework/src/com/intellij/codeInsight/daemon/quickFix/ActionHint.java.

References

• references/capabilities.md — every ModCommand, every factory method, and what the API can and cannot do
• references/psi-updater.md — psiUpdate, ModPsiUpdater, ActionContext
• references/recipes.md — before→after conversions, including replacing UI

External background (predates the current API — check spellings against references/capabilities.md):

• ModCommands: declarative API for intentions and quick-fixes (2023-06)
• ModCommand API status update (2023-12)
• API description & migration guide (Google Doc)