File Quick Actions

Map files to scripts. Right-click to execute.

A lightweight VS Code extension that eliminates the friction of running repetitive scripts on specific files. Define filename → script mappings in your user settings.json, then trigger them from the Explorer or editor right-click menu — no terminal navigation, no typing the same command again.

---

Table of Contents

• Why this extension?
• Install
• Quick start
• Configuration reference
• Supported variables
• Trigger methods
• Execution model
• Cross-platform notes
• Recipes
• Commands
• Troubleshooting
• FAQ
• Roadmap
• Contributing & development
• License

---

Why this extension?

If you maintain a project (PowerSchool plugins, build configs, deployment manifests, etc.) where the same handful of scripts get run against the same handful of files over and over, you know the cycle:

1. Find the file in the Explorer.
2. Open a terminal.
3. cd to the right directory.
4. Type the script invocation.
5. Watch it run.
6. Close the terminal.

File Quick Actions collapses that into a right-click → done.

Feature	File Quick Actions	VS Code Tasks	Shell Aliases
Right-click a file to run	✓	✗	✗
Per-file action mapping	✓	✗	✗
Multiple actions per file	✓	partial	✗
Visual indicator (Explorer badge)	✓	✗	✗
No terminal navigation needed	✓	requires task picker	✗
Plain JSON config	✓	✓	✗

---

Install

Marketplace

ext install file-quick-actions

(Or open the Extensions view, search File Quick Actions, click Install.)

Sideload a .vsix

git clone https://github.com/prince-park/file-quick-actions
cd file-quick-actions
yarn install
yarn package          # produces file-quick-actions-X.Y.Z.vsix
code --install-extension file-quick-actions-*.vsix

Requires: VS Code 1.92 or newer.

---

A copy-paste-ready example lives at sample.settings.json in this repo.

Quick start

1. Open user settings JSON (Cmd/Ctrl+Shift+P → Preferences: Open User Settings (JSON)).

2. Add a fileQuickActions block:

   "fileQuickActions": {
     "include": [
       {
         "name": "Validate Include",
         "script": "./scripts/validate.sh",
         "cwd": "${workspaceRoot}"
       }
     ]
   }
   

3. In the Explorer, right-click any file named include → File Quick Actions: Run... → Validate Include.

4. A terminal opens, runs ./scripts/validate.sh <file path>, and closes on success.

Files with mapped actions display a ⚡ badge in the Explorer.

---

Configuration reference

All configuration lives under the top-level setting fileQuickActions in settings.json. Keys are filenames (basename match, exact). Values are arrays of action objects.

"fileQuickActions": {
  "<filename>": [
    {
      "name": "<display name>",
      "script": "<path or PATH binary>",
      "cwd": "<working directory>",
      "closeTerminalOnSuccess": true
    }
  ]
}

Action fields

Field	Type	Required	Default	Description
name	string	✓	—	Display name shown in the context menu and Quick Pick.
script	string	✓	—	Absolute path, path relative to cwd, or the name of a binary on PATH. Supports variables.
cwd	string	✗	workspace root	Working directory for the script. Supports variables.
closeTerminalOnSuccess	boolean	✗	true	Auto-close the terminal when the script exits with code 0. On non-zero exit, the terminal always stays open.

Validation

Malformed entries are skipped (not thrown) so the extension stays usable. Validation warnings appear in the File Quick Actions Output channel (View → Output → File Quick Actions).

---

Supported variables

All variables can be used inside script and cwd. They expand at execution time, per file.

Variable	Expands to
${workspaceRoot}	Absolute path of the workspace folder containing the file
${workspaceName}	Name of the workspace folder
${filePath}	Full absolute path to the triggered file
${fileDir}	Directory containing the file
${fileName}	Filename only (e.g., include, plugin.xml)

Unknown tokens are left intact and logged once to the Output channel.

---

Trigger methods

Explorer right-click

Right-click any file in the Explorer view. If the basename matches a configured key, File Quick Actions: Run... appears in the navigation group at the bottom of the context menu.

Editor right-click

Same item appears in the right-click menu of the active editor and in the editor tab context menu.

Explorer badge

Files with at least one mapped action show a ⚡ badge in the Explorer. Hover for the list of action names.

Quick Pick

• 1 action mapped → runs immediately.
• 2+ actions mapped → a Quick Pick prompts you to choose which one to run.

---

Execution model

Given the action:

{
  "name": "Validate Include",
  "script": "./scripts/validate.sh",
  "cwd": "${workspaceRoot}",
  "closeTerminalOnSuccess": true
}

triggered on /workspace/MyProject/include, the extension:

1. Opens a fresh integrated terminal titled File Quick Actions: Validate Include.

2. Sets the working directory to the resolved cwd.

3. Exports the environment variable FILE_QUICK_ACTIONS_FILE=/workspace/MyProject/include.

4. Sends to the terminal:

   "./scripts/validate.sh" "/workspace/MyProject/include"; exit $?
   

5. Streams output live.

6. On exit code 0, if closeTerminalOnSuccess is true (default), disposes the terminal. Otherwise the terminal persists.

7. On any non-zero exit code, the terminal always stays open for inspection, and the exit code is logged to the Output channel.

Script inputs

Your script can read the target file via either of:

• Argument 1 — $1 (POSIX) / $args[0] (PowerShell)
• Environment variable — $FILE_QUICK_ACTIONS_FILE / $Env:FILE_QUICK_ACTIONS_FILE

Both are always set, simultaneously.

---

Cross-platform notes

The extension uses VS Code's integrated terminal, which honors your platform's default shell.

• macOS / Linux — assumes a POSIX shell (bash, zsh). Paths are double-quoted with ", $, `, and \ escaped.
• Windows (PowerShell) — paths are double-quoted with " escaped as ` "``.
• Windows (cmd.exe) — not officially supported. Switch your default integrated shell to PowerShell.

Make sure your scripts are executable (chmod +x script.sh on POSIX). The extension does not change file permissions.

---

Recipes

1 — Validate an include file at workspace root

"fileQuickActions": {
  "include": [
    {
      "name": "Validate Include",
      "script": "./scripts/validate-include.sh",
      "cwd": "${workspaceRoot}"
    }
  ]
}

2 — Multiple actions on one filename

"fileQuickActions": {
  "include": [
    { "name": "Validate", "script": "./scripts/validate.sh", "cwd": "${workspaceRoot}" },
    { "name": "Process",  "script": "./scripts/process.sh",  "cwd": "${workspaceRoot}" },
    { "name": "Deploy",   "script": "./scripts/deploy.sh",   "cwd": "${workspaceRoot}", "closeTerminalOnSuccess": false }
  ]
}

3 — Deploy a PowerSchool plugin.xml from ${filePath}/../..

"fileQuickActions": {
  "plugin.xml": [
    {
      "name": "Deploy Plugin",
      "script": "/usr/local/bin/deploy-plugin.sh",
      "cwd": "${filePath}/../..",
      "closeTerminalOnSuccess": false
    }
  ]
}

4 — Use a binary already on PATH

"fileQuickActions": {
  "include": [
    {
      "name": "Run Include Validator",
      "script": "include-validator",
      "cwd": "${workspaceRoot}"
    }
  ]
}

5 — Resolve script via a variable

"fileQuickActions": {
  "include": [
    {
      "name": "Validate",
      "script": "${workspaceRoot}/.scripts/validate.sh",
      "cwd": "${fileDir}"
    }
  ]
}

---

Commands

Command	Palette title	Notes
fileQuickActions.run	File Quick Actions: Run...	Invoked by context menus; can also be bound to a key.
fileQuickActions.reload	File Quick Actions: Reload Configuration	Manually re-reads fileQuickActions from settings.

Configuration is also reloaded automatically whenever fileQuickActions changes in any settings scope.

Bind a keyboard shortcut

// keybindings.json
{
  "key": "ctrl+alt+r",
  "command": "fileQuickActions.run",
  "when": "resourceFilename in fileQuickActions.knownFilenames"
}

---

Troubleshooting

"No actions configured for file"

The basename does not match any key under fileQuickActions in any active settings scope (User / Workspace / Folder). Confirm spelling and case.

Script not found / command not found

• Verify the script exists at the resolved path (check the Output channel for the exact command emitted).
• For relative paths, make sure cwd points where you expect.
• For PATH-based invocation, confirm the binary is on the PATH of the integrated terminal's shell (which inherits your login shell config — ~/.zshrc, ~/.bash_profile, etc.).

Terminal stays open even on success

• closeTerminalOnSuccess may be set to false.
• The script may have exited with a non-zero code; check the last line of the terminal.
• The extension waits for the shell to exit (it appends ; exit $?). If your script intentionally backgrounds work and doesn't return, the terminal will stay open.

Variables not expanding

• Only the supported variables are expanded — VS Code's own task variables are not.
• Unknown ${...} tokens are passed through verbatim.

Permission denied

chmod +x your-script.sh. The extension does not modify file permissions.

Where do I see logs?

View → Output → File Quick Actions shows the loaded config, validation warnings, every action invocation, and exit codes.

---

FAQ

Q: Does the extension work on a folder, not a file? A: No — current scope is single files. Folder support is a candidate for a future release.

Q: Can I match by extension or glob, not exact filename? A: Not in v0.0.1. Exact basename only. Glob matching is on the roadmap.

Q: Does the extension execute scripts on its own? A: No. Scripts only run when you explicitly invoke them via menu / Quick Pick / keybinding. You own the config and the scripts.

Q: Can different workspaces have different mappings? A: Yes — fileQuickActions honors User, Workspace, and Folder settings scopes (workspace overrides user, folder overrides workspace).

---

Roadmap

• Glob / extension-based filename matching
• Keyboard shortcut presets per action
• Action groups (sequenced multi-script runs)
• Optional input prompts before execution (variables from QuickInput)
• Output parsing (warnings/errors highlighted)
• Workspace-scoped script templates

---

Contributing & development

git clone https://github.com/prince-park/file-quick-actions
cd file-quick-actions
yarn install
yarn compile           # type-check + build to ./out

• Press F5 in VS Code to launch an Extension Development Host with this extension loaded.
• Add a fileQuickActions block in the dev host's user settings to try mappings live.
• yarn test runs the headless extension test suite via @vscode/test-electron.
• yarn lint runs ESLint.
• yarn package builds a publishable .vsix.

Project layout

file-quick-actions/
├── package.json                         # manifest, contributes.{commands,menus,configuration}
├── tsconfig.json
├── README.md
├── CHANGELOG.md
├── LICENSE
└── src/
    ├── extension.ts                     # activate() / deactivate()
    ├── config/
    │   ├── configLoader.ts              # read + validate fileQuickActions
    │   └── types.ts
    ├── variables/
    │   └── substitute.ts                # ${workspaceRoot} etc.
    ├── runner/
    │   ├── actionRunner.ts              # terminal spawn + env + auto-close
    │   ├── terminalManager.ts           # tracks terminals, watches exit status
    │   └── quoting.ts                   # shell-safe quoting (posix + powershell)
    ├── ui/
    │   ├── fileDecorationProvider.ts    # ⚡ Explorer badge
    │   ├── quickPick.ts                 # action picker when N > 1
    │   └── (commandRegistrar embedded in extension.ts)
    └── test/
        ├── runTest.ts
        └── suite/
            ├── index.ts
            ├── substitute.test.ts
            ├── quoting.test.ts
            └── configLoader.test.ts

Pull requests

PRs welcome. Please:

• Add or update tests for any behavior change.
• Run yarn lint and yarn test locally before opening the PR.
• Update CHANGELOG.md under an ## [Unreleased] section.

---

License

MIT © 2026 Prince Park