> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fabriqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Runner

> Run workspace tasks from Fabriqa using VS Code and Fabriqa task file formats, with variable resolution, platform overrides, and task dependencies.

# Task Runner

The Fabriqa task runner lets you define and execute workspace tasks — build commands, test runners, dev servers — directly from the app without leaving your chat context. It reads the same `tasks.json` format used by VS Code, so existing project task configurations work immediately.

## Task File Locations

Fabriqa looks for task definitions in this priority order:

1. **`.fabriqa/tasks.json`** — Fabriqa-specific task file (takes precedence).
2. **`.vscode/tasks.json`** — VS Code task file (used if no Fabriqa file is found).

Both files use the same format. The `.fabriqa/tasks.json` file is useful when you want Fabriqa-specific tasks that shouldn't appear in VS Code's task runner.

A custom path can also be set per workspace in **Workspace Settings → Overview**.

## Task File Format

Task files use the VS Code `tasks.json` format with `"version": "2.0.0"`. The format supports JSONC (JSON with comments).

```jsonc theme={null}
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Dev",
      "type": "shell",
      "command": "npm run dev",
      "options": {
        "cwd": "${workspaceFolder}"
      }
    },
    {
      "label": "Build",
      "type": "shell",
      "command": "npm run build",
      "options": {
        "cwd": "${workspaceFolder}"
      }
    },
    {
      "label": "Test",
      "type": "shell",
      "command": "npm test",
      "args": ["--coverage"],
      "options": {
        "cwd": "${workspaceFolder}"
      }
    }
  ]
}
```

Each task requires at minimum a `label` and a `command`.

## Variable Resolution

Use VS Code-compatible variables in `command`, `args`, and `options.cwd`:

| Variable                     | Resolved Value                           |
| ---------------------------- | ---------------------------------------- |
| `${workspaceFolder}`         | Absolute path to the workspace root      |
| `${workspaceFolderBasename}` | Folder name only (no path)               |
| `${cwd}`                     | Same as `${workspaceFolder}`             |
| `${pathSeparator}` or `${/}` | `/` on macOS/Linux, `\` on Windows       |
| `${env:VAR_NAME}`            | Value of environment variable `VAR_NAME` |

Example using variables:

```jsonc theme={null}
{
  "label": "Start Server",
  "type": "shell",
  "command": "node",
  "args": ["${workspaceFolder}/server.js"],
  "options": {
    "cwd": "${workspaceFolder}/packages/api"
  }
}
```

## Task Arguments

Pass arguments via the `args` array. Arguments are automatically shell-escaped:

```jsonc theme={null}
{
  "label": "Lint",
  "type": "shell",
  "command": "eslint",
  "args": ["src", "--ext", ".ts,.tsx", "--fix"]
}
```

## Platform-Specific Overrides

Override any task property for a specific platform using `windows`, `osx`, or `linux` keys:

```jsonc theme={null}
{
  "label": "Open Editor",
  "type": "shell",
  "command": "code .",
  "windows": {
    "command": "code.cmd ."
  },
  "linux": {
    "command": "code-insiders ."
  }
}
```

The platform override merges on top of the base task definition. Only the specified properties are overridden.

## Task Dependencies

Use `dependsOn` to chain tasks. Dependencies run before the task's own command:

```jsonc theme={null}
{
  "label": "Build and Test",
  "type": "shell",
  "command": "echo 'All done'",
  "dependsOn": ["Build", "Test"]
}
```

`dependsOn` accepts a single task label (string) or an array of labels. Dependencies are resolved recursively and concatenated with `&&` — if any dependency fails, the chain stops.

<Warning>
  Circular dependencies are detected and skipped. A task that depends on itself (directly or transitively) will not cause an infinite loop — the cycle is broken and the circular portion is omitted.
</Warning>

## Running Tasks

Tasks appear in the **Run** button dropdown in the chat header toolbar:

1. Click the **Run** button (▶) to open the actions menu.
2. Select a task from the list to execute it.
3. The task runs in the integrated terminal panel.

### Run Last Action

**`Cmd+R`** (macOS) / **`Ctrl+R`** (Windows / Linux)

Reruns the most recently selected task without opening the menu. If no task has been run yet, `Cmd+R` opens the actions menu instead.

The last selected task is persisted per workspace across restarts.

## Adding Tasks via the UI

If no task file exists yet, click **Add action** in the Run menu to open a task definition editor. Fabriqa creates a `.fabriqa/tasks.json` with a starter template and opens it for editing.

You can also add tasks from **Workspace Settings → Actions**.

## Example: Monorepo Setup

```jsonc theme={null}
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Install",
      "type": "shell",
      "command": "npm install",
      "options": { "cwd": "${workspaceFolder}" }
    },
    {
      "label": "Build All",
      "type": "shell",
      "command": "npm run build --workspaces",
      "dependsOn": ["Install"],
      "options": { "cwd": "${workspaceFolder}" }
    },
    {
      "label": "Dev API",
      "type": "shell",
      "command": "npm run dev",
      "options": { "cwd": "${workspaceFolder}/packages/api" }
    },
    {
      "label": "Dev Web",
      "type": "shell",
      "command": "npm run dev",
      "options": { "cwd": "${workspaceFolder}/packages/web" }
    }
  ]
}
```