Action Group Executer

Start everything you need for a workflow with one shortcut. An action group combines VS Code tasks, VS Code commands, terminals, background processes and a debug session, and starts them all together.

Quick start

1. Run ActionGroupExec: Create Action Group from the Command Palette.
2. Give the group a name and add actions, e.g. your build task and the clangd.restart command, then click Create.
3. Press Ctrl+Shift+A / Cmd+Shift+A (ActionGroupExec: Execute Action Group) and pick the group.

Commands

The action group editor

ActionGroupExec: Edit Action Groups opens an editor tab for all action groups. The left side lists the groups of all settings locations (workspace, workspace folders and user settings) sorted by group folder. The right side shows the selected group as a form.

• Tasks and debug sessions are selected from the tasks and launch configurations of your workspace, including npm scripts and tasks of other extensions.
• VS Code commands can be searched by ID or title, e.g. clangd.restart.
• Terminals and processes are entered as command lines, with name, working directory and delay.
• Saved in decides where the group is stored. Workspace settings can be shared with your team, user settings apply to all your workspaces. Changing it moves the group.

Unsaved changes are kept per group while you switch between groups and marked with ●. Save with the button or Ctrl+S / Cmd+S. If the settings were changed elsewhere in the meantime, the editor doesn't overwrite them.

Saving rewrites the actionGroupExecuter.actionGroups setting, so comments inside it are lost. Options the editor doesn't show, e.g. environment variables, are kept. Processes with sequential commands and inline debug configurations (newConfiguration) can only be removed in the editor, edit them in the settings JSON.

Configuring action groups in the settings

Action groups are stored in the actionGroupExecuter.actionGroups setting. Besides using the editor, you can edit them in the settings JSON: in the workspace settings (.vscode/settings.json), the user settings or a .code-workspace file. Every group needs a name and at least one action:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Build and run",
            "terminals": [{ "command": "npm run build && npm start" }]
        }
    ]
}

All actions of a group start at the same time. Use the delay options to start an action later, e.g. a debug session after a server is up.

Tasks

Start tasks from tasks.json or tasks provided by extensions, e.g. npm scripts. Tasks are found by their name (label). This group starts the build task of tasks.json and, two seconds later, the watch script of package.json:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Build and watch",
            "tasks": [
                { "name": "build" },
                { "name": "watch", "source": "npm", "delayTask": 2000 }
            ]
        }
    ]
}

// .vscode/tasks.json
{
    "version": "2.0.0",
    "tasks": [
        { "label": "build", "type": "shell", "command": "make" }
    ]
}

// package.json
{
    "name": "my-app",
    "scripts": { "watch": "tsc --watch" }
}

VS Code commands

Execute any command from the Command Palette or an extension by its ID. You can copy the ID with "Copy Command ID" in the context menu of the Keyboard Shortcuts editor.

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Save and restart clangd",
            "commands": [
                { "id": "workbench.action.files.saveAll" },
                { "id": "clangd.restart", "delayCommand": 500 },
                { "id": "workbench.action.quickOpen", "args": ["${fileBasename}"] }
            ]
        }
    ]
}

Terminals

Send a command to an integrated terminal. The terminal is reused when one with the same name exists.

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Server with logs",
            "terminals": [
                { "name": "Server", "command": "npm start" },
                {
                    "name": "Logs",
                    "command": "tail -f server.log",
                    "delayCommand": 5000,
                    "disposeOldTerminal": true,
                    "extendedOptions": { "cwd": "${workspaceFolder}/logs" }
                }
            ]
        }
    ]
}

A terminal runs one command line. To run several commands, combine them, e.g. echo Hello1 && sleep 10 && echo Hello2.

Processes

Run a program in the background and show its output in an editor tab. Program and arguments are separate strings, so no quoting is needed. Every entry of processes gets its own output tab, so several entries run in parallel:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "List files",
            "processes": [
                {
                    "name": "Home",
                    "command": { "call": ["ls", "-la", "${env:HOME}"] }
                },
                {
                    "name": "Workspace",
                    "command": {
                        "call": ["ls", "-la"],
                        "extendedOptions": { "cwd": "${workspaceFolder}", "env": { "LANG": "C" } }
                    }
                }
            ]
        }
    ]
}

To run commands one after another in the same tab, use commands instead of command:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Install and test",
            "processes": [
                {
                    "printCommand": true,
                    "commands": [
                        { "call": ["npm", "ci"], "processEndMessage": "\nInstalled.\n" },
                        { "call": ["npm", "test"], "processEndMessage": "\nTests ended with ${returnCode}.\n" }
                    ]
                }
            ]
        }
    ]
}

Options of each command:

Environment variables like $HOME are not resolved in call, use ${env:HOME} instead.

Debug sessions

Start a launch configuration from launch.json by its name. This group starts the server in a terminal and attaches the debugger three seconds later:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Debug server",
            "terminals": [{ "command": "node --inspect server.js" }],
            "debugSession": {
                "namedConfiguration": "Attach to server",
                "delaySession": 3000
            }
        }
    ]
}

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        { "name": "Attach to server", "type": "node", "request": "attach", "port": 9229 }
    ]
}

A launch configuration can also be defined inline with newConfiguration. Here the debugger asks for additional arguments when the group starts:

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Debug current Python file",
            "debugSession": {
                "newConfiguration": {
                    "name": "Debug current file",
                    "type": "python",
                    "request": "launch",
                    "program": "${file}",
                    "args": []
                },
                "requestUserInputArguments": true
            }
        }
    ]
}

Debugging processes and terminals

Processes and terminals can also be started in the debugger instead. When a group contains such actions, Execute Action Group asks which one to debug, or none.

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Run scripts",
            "processes": [
                // Uses defaultProcessDebugTemplate.
                { "name": "Script 1", "command": { "call": ["./script1.py", "--verbose"] } },
                {
                    "name": "Script 2",
                    "command": {
                        "call": ["./script2.py"],
                        // Takes priority over defaultProcessDebugTemplate.
                        "debugTemplate": { "type": "python", "request": "launch", "justMyCode": false }
                    }
                }
            ],
            "terminals": [
                { "name": "Script 3", "command": "./script3.py", "useProcessDefaultDebugConfig": true }
            ],
            "defaultProcessDebugTemplate": { "type": "python", "request": "launch", "console": "integratedTerminal" }
        }
    ]
}

The program, arguments and working directory of the selected action are added to the template. A process is debuggable when it has a single command and a debugTemplate or defaultProcessDebugTemplate. A terminal is debuggable with a debugTemplate, or with useProcessDefaultDebugConfig and a defaultProcessDebugTemplate. Groups with a debugSession don't ask.

Group folders and order

groupNames shows a group inside folders of the Execute Action Group list, like directories. sortingIndex orders groups and folders, lower numbers come first. Typing a search term also finds the groups inside the subfolders of the current folder, shown with their folder path.

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Start server",
            "groupNames": [{ "name": "Backend", "sortingIndex": 1 }],
            "terminals": [{ "command": "npm run server" }]
        },
        {
            "name": "Run integration tests",
            "groupNames": [{ "name": "Backend" }, { "name": "Tests" }],
            "sortingIndex": 2,
            "terminals": [{ "command": "npm run test:integration" }]
        }
    ]
}

Keyboard shortcuts

A single action group can get its own keyboard shortcut. Add it in Preferences: Open Keyboard Shortcuts (JSON) and pass the group's name as argument. groupNames (the folder names, outermost first) is only needed when several groups have the same name.

// .vscode/settings.json
{
    "actionGroupExecuter.actionGroups": [
        {
            "name": "Run unit tests",
            "groupNames": [{ "name": "Backend" }],
            "terminals": [{ "command": "npm test" }]
        }
    ]
}

// keybindings.json
[
    {
        "key": "ctrl+alt+t",
        "mac": "cmd+alt+t",
        "command": "action-group-executer.executeActionGroup",
        "args": { "name": "Run unit tests", "groupNames": ["Backend"] }
    }
]

Variables

All strings can use these VS Code predefined variables: ${cwd}, ${fileBasenameNoExtensions}, ${fileBasename}, ${fileDirname}, ${fileExtname}, ${file}, ${lineNumber}, ${pathSeparator}, ${relativeFileDirname}, ${relativeFile}, ${selectedText}, ${workspaceFolderBasename} and ${workspaceFolder}. ${env:NAME} is replaced with the environment variable NAME.

The file variables refer to the active editor. When a non-text tab is active, e.g. an image or SVG preview, they refer to the file of that tab.

The newConfiguration of debug sessions and the extendedOptions of terminals support all VS Code predefined variables.

Extension settings

// User settings (settings.json)
{
    "actionGroupExecuter.defaultProcessEndMessage": "\n\nProcess ended with ${returnCode}.\n",
    "actionGroupExecuter.defaultFileAssociation": "log",
    "actionGroupExecuter.defaultShowActionSource": false
}

Known issues

• Running processes are not restored when a window is closed.
• Process output tabs are created with a 500 ms delay, otherwise VS Code fails to create the next tab.
• When starting a debugger, VS Code asks to save the current file.
• When a process is debugged, its output goes to the debug console instead of an output tab.
• Sequential process commands don't check the exit code of the previous command.
• Additional arguments entered for requestUserInputArguments are not validated.

Release notes

See CHANGELOG.md.