Tasks - Visual Studio Code

Overview

Tasks in Visual Studio Code allow you to automate common workflows like building, testing, and deploying your code. Tasks can run shell commands, scripts, and integrate with build tools like Make, Gulp, or npm scripts.

Getting Started

Access Tasks

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) and type “Tasks”

Configure Task

Select “Tasks: Configure Task” to create a tasks.json file

Run Task

Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS) to run the default build task

Task Configuration

Tasks are defined in .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Project",
      "type": "shell",
      "command": "npm run build",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": ["$tsc"],
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ]
}

Task Types

Shell Tasks

Run shell commands:

// From VS Code source: src/vs/workbench/contrib/tasks/common/tasks.ts
export enum ShellQuoting {
  Escape = 1,  // Use character escaping
  Strong = 2,  // Use strong quoting
  Weak = 3,    // Use weak quoting
}

export interface IShellConfiguration {
  executable?: string;
  args?: string[];
  quoting?: IShellQuotingOptions;
}

{
  "label": "Echo",
  "type": "shell",
  "command": "echo Hello World"
}

Process Tasks

Run processes directly without a shell:

{
  "label": "Run Node",
  "type": "process",
  "command": "node",
  "args": ["${workspaceFolder}/app.js"],
  "options": {
    "cwd": "${workspaceFolder}"
  }
}

Real Examples from VS Code

Here are actual task configurations from the VS Code source repository:

Build Task with Problem Matcher

{
  "type": "npm",
  "script": "watch-client-transpiled",
  "label": "Core - Transpile",
  "isBackground": true,
  "presentation": {
    "reveal": "never",
    "group": "buildWatchers",
    "close": false
  },
  "problemMatcher": {
    "owner": "esbuild",
    "applyTo": "closedDocuments",
    "fileLocation": ["relative", "${workspaceFolder}/src"],
    "pattern": {
      "regexp": "^(.+?):(\\d+):(\\d+): ERROR: (.+)$",
      "file": 1,
      "line": 2,
      "column": 3,
      "message": 4
    },
    "background": {
      "beginsPattern": "Starting transpilation\\.\\.\\.",
      "endsPattern": "Finished transpilation with"
    }
  }
}

Composite Task

{
  "label": "VS Code - Build",
  "dependsOn": [
    "Core - Transpile",
    "Core - Typecheck",
    "Ext - Build"
  ],
  "group": {
    "kind": "build",
    "isDefault": true
  },
  "problemMatcher": []
}

Background Task for Development

{
  "type": "shell",
  "command": "./scripts/code-server.sh",
  "args": ["--no-launch", "--port", "8080"],
  "label": "Run code server",
  "isBackground": true,
  "problemMatcher": {
    "pattern": {"regexp": ""},
    "background": {
      "beginsPattern": ".*node .*",
      "endsPattern": "Web UI available at .*"
    }
  },
  "presentation": {
    "reveal": "never"
  }
}

Task Properties

Essential Properties

export interface ITaskIdentifier {
  type: string;  // Task type (shell, process, npm, etc.)
}

export const CUSTOMIZED_TASK_TYPE = '$customized';

Property	Description	Required
`label`	Task name displayed in UI	Yes
`type`	Task type (shell, process, npm)	Yes
`command`	Command to execute	Yes
`args`	Command arguments	No
`group`	Task group (build, test)	No
`problemMatcher`	Error pattern matcher	No
`presentation`	Terminal presentation options	No

Task Groups

Organize tasks into groups:

Task Groups

build: Build tasks (default: Ctrl+Shift+B / Cmd+Shift+B)
test: Test tasks
none: No group
custom: User-defined groups

{
  "group": {
    "kind": "build",
    "isDefault": true
  }
}

Problem Matchers

Problem matchers parse output to detect errors and warnings:

{
  "problemMatcher": {
    "owner": "typescript",
    "fileLocation": ["absolute"],
    "pattern": {
      "regexp": "Error: ([^(]+)\\((\\d+|\\d+,\\d+|\\d+,\\d+,\\d+,\\d+)\\): (.*)$",
      "file": 1,
      "location": 2,
      "message": 3
    }
  }
}

Built-in Problem Matchers

{
  "problemMatcher": "$tsc"
}

Background Tasks

For watch mode and long-running tasks:

{
  "problemMatcher": {
    "owner": "typescript",
    "fileLocation": "absolute",
    "pattern": {
      "regexp": "Error: ([^(]+)\\((\\d+,\\d+)\\): (.*)$",
      "file": 1,
      "location": 2,
      "message": 3
    },
    "background": {
      "activeOnStart": true,
      "beginsPattern": "Starting compilation",
      "endsPattern": "Finished compilation"
    }
  }
}

Task Variables

Use variables for flexible task definitions:

Variable	Description
`${workspaceFolder}`	Workspace root path
`${workspaceFolderBasename}`	Workspace folder name
`${file}`	Current opened file
`${fileBasename}`	Current file name
`${fileDirname}`	Current file directory
`${fileExtname}`	Current file extension
`${cwd}`	Current working directory
`${env:VAR}`	Environment variable
`${config:setting}`	VS Code setting value

{
  "label": "Build Current File",
  "type": "shell",
  "command": "gcc",
  "args": [
    "-o",
    "${fileDirname}/${fileBasenameNoExtension}",
    "${file}"
  ]
}

Task Dependencies

Run tasks in sequence or parallel:

{
  "label": "Build All",
  "dependsOn": ["Clean", "Compile", "Package"],
  "dependsOrder": "sequence"
}

Use dependsOrder: "parallel" to run dependent tasks simultaneously for faster builds.

Presentation Options

Control how task output is displayed:

{
  "presentation": {
    "echo": true,
    "reveal": "always",
    "focus": false,
    "panel": "shared",
    "showReuseMessage": true,
    "clear": false,
    "group": "build"
  }
}

Presentation Properties

Property	Values	Description
`reveal`	`always`, `never`, `silent`	When to show terminal
`panel`	`shared`, `dedicated`, `new`	Terminal reuse
`focus`	`true`, `false`	Focus terminal on run
`clear`	`true`, `false`	Clear before running
`group`	string	Group related tasks

Task Context Keys

export const TASK_RUNNING_STATE = new RawContextKey<boolean>(
  'taskRunning', 
  false, 
  'Whether a task is currently running'
);

export const TASK_TERMINAL_ACTIVE = new RawContextKey<boolean>(
  'taskTerminalActive', 
  false, 
  'Whether the active terminal is a task terminal'
);

Running Tasks

Command Palette

Tasks: Run Task - Select and run any task
Tasks: Run Build Task - Run default build task (Ctrl+Shift+B / Cmd+Shift+B)
Tasks: Run Test Task - Run test tasks
Tasks: Rerun Last Task - Run the last executed task
Tasks: Terminate Task - Stop running task

Keyboard Shortcuts

Action	Windows/Linux	macOS
Run Build Task	`Ctrl+Shift+B`	`Cmd+Shift+B`
Run Task	`Ctrl+Shift+P` > Tasks	`Cmd+Shift+P` > Tasks

Bind frequently used tasks to custom keyboard shortcuts in keybindings.json.

Task Output Scanning

Monitor task output for specific patterns:

export interface ITerminalExitReason {
  code: number | undefined;
  signal: string | undefined;
}

Auto-detected Tasks

VS Code automatically detects tasks from:

Auto-detected Task Sources

npm scripts in package.json
Gulp tasks in gulpfile.js
Grunt tasks in Gruntfile.js
Jake tasks in Jakefile
Make targets in Makefile

{
  "typescript.tsc.autoDetect": "on",
  "gulp.autoDetect": "on",
  "grunt.autoDetect": "on",
  "npm.autoDetect": "on"
}

Task Execution

Options

Configure execution environment:

{
  "label": "Custom Environment",
  "type": "shell",
  "command": "node script.js",
  "options": {
    "cwd": "${workspaceFolder}/src",
    "env": {
      "NODE_ENV": "production",
      "API_KEY": "${env:API_KEY}"
    },
    "shell": {
      "executable": "/bin/bash",
      "args": ["-l"]
    }
  }
}

Shell Quoting

export interface IShellQuotingOptions {
  escape?: string | {
    escapeChar: string;
    charsToEscape: string;
  };
  strong?: string;
  weak?: string;
}

Advanced Features

Input Variables

Prompt for user input:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Deploy",
      "type": "shell",
      "command": "deploy",
      "args": ["${input:environment}"]
    }
  ],
  "inputs": [
    {
      "id": "environment",
      "type": "pickString",
      "description": "Select deployment environment",
      "options": ["development", "staging", "production"],
      "default": "development"
    }
  ]
}

Compound Tasks

Run multiple tasks together:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Client Build",
      "command": "npm run build:client",
      "type": "shell"
    },
    {
      "label": "Server Build",
      "command": "npm run build:server",
      "type": "shell"
    },
    {
      "label": "Full Build",
      "dependsOn": ["Client Build", "Server Build"],
      "dependsOrder": "parallel",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Best Practices

Use background tasks for watch mode commands that continue running. This allows you to run other tasks without interruption.

Avoid using task labels that conflict with auto-detected tasks. Use unique, descriptive names.

Task Organization

Group related tasks using presentation groups
Use clear, descriptive labels
Set appropriate problem matchers
Configure keyboard shortcuts for frequent tasks
Document complex tasks with comments (using "detail" property)

{
  "label": "Deploy to Production",
  "detail": "Builds, tests, and deploys to production server",
  "type": "shell",
  "command": "npm run deploy"
}

Troubleshooting

Task not running
- Check task syntax in tasks.json
- Verify command is in PATH
- Check working directory
Problem matcher not working
- Verify regex pattern matches output
- Check file location settings
- Test with built-in matchers first
Output not showing
- Check presentation.reveal setting
- Verify terminal is not hidden
- Look in “Problems” panel for parsed errors

Use "tasks.verboseLogging": true in settings to enable detailed task execution logs.

Get Started

Core Features

Extensions

Customization

Languages

​Overview

​Getting Started

​Task Configuration

​Task Types

​Shell Tasks

​Process Tasks

​Real Examples from VS Code

​Build Task with Problem Matcher

​Composite Task

​Background Task for Development

​Task Properties

​Essential Properties

​Task Groups

Task Groups

​Problem Matchers

​Built-in Problem Matchers

​Background Tasks

​Task Variables

​Task Dependencies

​Presentation Options

​Presentation Properties

​Task Context Keys

​Running Tasks

​Command Palette

​Keyboard Shortcuts

​Task Output Scanning

​Auto-detected Tasks

Auto-detected Task Sources

​Task Execution

​Options

​Shell Quoting

​Advanced Features

​Input Variables

​Compound Tasks

​Best Practices

​Task Organization

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Getting Started

Task Configuration

Task Types

Shell Tasks

Process Tasks

Real Examples from VS Code

Build Task with Problem Matcher

Composite Task

Background Task for Development

Task Properties

Essential Properties

Task Groups

Problem Matchers

Built-in Problem Matchers

Background Tasks

Task Variables

Task Dependencies

Presentation Options

Presentation Properties

Task Context Keys

Running Tasks

Command Palette

Keyboard Shortcuts

Task Output Scanning

Auto-detected Tasks

Task Execution

Options

Shell Quoting

Advanced Features

Input Variables

Compound Tasks

Best Practices

Task Organization

Troubleshooting