Macros for VS Code

A macro is a JavaScript script that lets you automate tasks or add custom tools to VS Code using its standard extensibility APIs but without the overhead of maintaining a full extension. Macros are ideal for workspace-specific automation, enhancing your workflow with custom utilities, or quickly prototyping extension features.

Implementation-wise, these macro scripts are executed within sandboxes hosted within the process of this extension. This approach provides isolated execution, with full access to vscode and NodeJS APIs.

Getting Started

1. Create a new macro:

   • Option 1: Use the Macros: New Macro command.
   • Option 2: Create an empty javascript editor and use the Macros: Fill File with Template command.
   • Option 3: Ask the @macros chat agent to create a macro for you.

   ℹ️ Save your macro files using a .macro.js extension. This enables UI controls, IntelliSense, and other macro-specific features.

2. Write, or update, your macro code.

   • See Available References.

   Example: "Hello, World!" macro

   vscode.window.showInformationMessage("Hello, world!");
   

   Example: Async "Hello, World!" macro

   async function main() {
     const yes = { title: 'Yes' };
     const no = { title: 'No', isCloseAffordance: true };
   
     let answer;
     do {
       answer = await vscode.window.showInformationMessage(
         `Hello, World!. Close this dialog?`, { modal: true }, yes, no);
     } while (answer !== yes);
   }
   
   main()
   

3. From the Command Palette, use the Macros: Run Active Editor as Macro command to execute your macro. Alternatively, on untitled, javascript or *.macro.js, editors, use the run and debug buttons will be available on the editor title bar.

   

Stopping a Macro

1. Use the Macro Explorer View to stop specific run isntances or all instances for a given macro.

2. Use the Macros: Show Running Macros command and click the stop button to request the macro to stop.

A macro sandbox cannot be terminated; instead, the Stop action sends a cancellation request via the __cancellationToken (CancellationToken) variable to the macro. This variable must be wired into all async code and APIs.

If a macro does not respond to the cancellation request, it will continue running. In such cases, you can use the Developer: Restart Extension Host command to restart all extensions, or simply restart VS Code to stop the macro. While this is not ideal, it provides a way to recover from unresponsive or runaway macros. Note that this approach will not implicitly terminate external processes started by the macro.

Running a Macro on startup

You can run macros on startup using the macros.startupMacros setting. This setting accepts paths to specific macro files (not directories), which are executed when a workspace is opened or when VS Code starts without one. Paths pointing to non-existent or empty files are automatically ignored (see the Macros log for details), but logic errors will trigger an error dialog.

Startup macros let you define logic equivalent to an extension’s activate method. When appropriate, add cleanup logic using __disposables member.

Workspace Trust Startup macro execution is disabled in untrusted workspaces.

Keybinding a Macro

Keybind the macros.run command with a single argument that is the path to the macro to run. This can only be done directly in the keybindings.json file, however. Check the VS Code documentation for details.

1. Use the Preferences: Open Keyboard Shortcuts (JSON) command to open the keybindings.json file.

2. Add a keybinding for the macros.run command passing as argument the path to the macro file to run (${userhome} and ${workspaceFolder} tokens are supported), e.g.

   Example: Keybinding definition

   [
     {
       "key": "Shift+Alt+X",
       "command": "macros.run",
       "args": "${userhome}/macros/references.macro.js",
       "when": "editorTextFocus"
     }
   ]
   

Commands

Debugging

See Debugging a Macro for additional information.

• Macros: Debug Active File as Macro: debug current editor as a macro (document will be saved before running).
• Macro: Debug Macro: select a macro file to debug. Provides access to configured macros.sourceDirectories.

Development

• Macros: New REPL: start a REPL whose context matches the one used when running macros.
  • Use .help for list of available commands.
• Macros: Setup Source Directory for Development: adds or updates optional files used to improve IntelliSense on macro files. This action is run automatically in the background when saving a .macro.js file, provided that macros.sourceDirectories.verify is enabled.

Manage Macros

• Macros: Fill File with Template: initialize an existing file with example macro content.
• Macros: New Macro: creates a new file with example macro content.
• Macros: Show Running Macros: view and manage running macros.

Run Macros

• Macros: Run Active File as Macro: run current editor as a macro (document will be saved before running).
• Macros: Rerun Last Macro: execute the most recently run macro.
• Macros: Run Macro: select a macro to run. Provides access to macros in configured macros.sourceDirectories directories.

Macro Explorer View

The Macro Explorer provides a central management view for macros. You can use the Macros: Show Macro Explorer command to bring it into view.

• Macro Library Folders: configure macro folders, browse their contents, and quickly add, delete, or move macro files around using drag-and-drop.

  • "Temporary": this is a virtual library node that shows all untitled macro documents allowing to easily manage all your in-memory macros.

• Macros: edit, run, or debug macros with a once-click.

• Macro Run Instances: see active runs. Stop existing ones directly from the view. This is more convenient than the Macros: Show Running Macros command but it does not replace it as in-memory runs do not have a representation here.

  • This view shows options used when a given instance was created.

Development

Available Code References

The following references are available from the global context of your macro:

• vscode: symbol that provides access to the VS Code APIs.
• macros: symbol that provides access to this extension's API (see Macros API).
• require: method that allows load Node.js libraries. Version is same as your installed VS Code's (see About option).
• Other: atob, btoa, clearInterval, clearTimeout, crypto, fetch, global, require, setInterval, setTimeout.

macros API

• log: Provides access to the Macros log output channel, allowing macros to write log entries as needed.

• macro: Current macro.

  • uri: URI of macro. It is undefined if running from an in-memory buffer.

  Example: Macros API

  vscode.window.showInformationMessage(`Hello from ${macros.macro.uri.fsPath}!`);
  macros.log.info('Greeted the world');
  

Predefined Views and View Container

Views such as sidebars and panels cannot be created dynamically—they must first be declared in the extension's package.json manifest. This limitation means macros would not be able to define their own views at runtime. To overcome this limitation, the extension predefines a Macros view container (with the id: macrosViews) with generic webview and treeview views (with ids macrosView.webview[1..3] and macrosView.treeview[1..3]). Macros can then claim and use these predefined views to display custom content or UI as needed.

Views are disabled by default via a context value, so to enable them you must enable that context value (see example below).

Example: Enabling macrosView.webview1 view

vscode.commands.executeCommand('setContext', 'macrosView.webview1.show', true);

Remember to set this back to false when macro completes.

Macro-backed tree view ("Tree View" template)

Special Tokens

These tokens do not form part of contexts shared when @macro:persistent is used as they are different from session to session.

• __cancellationToken: a CancellationToken used by th extension to notify about a stop request. See Stopping a Macro.
• __disposables: an array for adding Disposable instances, which will be automatically disposed of when the macro completes.
• __runId: Id of the current macro execution session.
• __startup: Whether current macro execution session was triggered during startup.

Macro Options

An option is added to macro file as a comment in the form //@macro:«option»[,…«option»]. The following options are available:

• persistent: All invocations of the macro use the same execution context so global variables persist across runs. Use the Reset Context CodeLens to reinitialize context.
• retained: An instance of the macro will remain active until explicitly stopped, e.g., using the Macros: Show Running Macros command. This removes the need to await __cancellationToken.onCancellationRequested (or similar signal) to keep the macro's services and listeners running.
• singleton: Only one instance of the macro may run at a time; additional invocations fail.

// @macro:singleton
// Example: Hello World!
vscode.window.showInformationMessage("Hello, world!");

Download Definition Files

Any URL in a macro file pointing to a .d.ts file will automatically receive a code action, Download .d.ts, enabling you to download the file directly to the macro's parent folder. This simplifies adding type definitions to support IntelliSense in your macros.

For GitHub URLs containing /blob/, the extension offers special handling by converting them to their raw equivalent. For example: https://github.com/Microsoft/vscode/blob/main/extensions/git/src/api/git.d.ts is automatically handled as https://github.com/Microsoft/vscode/raw/refs/heads/main/extensions/git/src/api/git.d.ts.

For all other URLs, a standard HTTP GET request is sent to download the file.

Debugging a Macro

Debugging a macro leverages VS Code's extension debugging story since the macros are run in the context of this extension. This makes the experience a bit awkward as a new VS Code instance is launched, and you need to open the right context (e.g. workspace) in that new instance to debug your macro (vs, for example, launching another VS Code instance and attaching to the current one).