VSCode Deck

A Stream Deck–style button grid for VSCode. Configure buttons in a JSON file, click them to run VSCode commands or shell commands — singly or as sequential chains. Works in a sidebar panel or a floating window.

Designed as a single place to collect the commands you run the most: mvn clean install, npm run dev, git pull, "save all + format", opening tools, kicking off deploy scripts, whatever you wish your IDE had a one-click button for.

Features

• Sidebar or floating window — pick your layout in the config.
• Visual editor — drag-and-drop reorder within and across categories, inline edit, live preview. No JSON required.
• IntelliSense in deck.json — autocomplete, type-checking, hover docs, and inline color picker via a bundled JSON schema.
• Running indicator with click-to-cancel — buttons show a spinner while running; click again to kill the process tree.
• Full keybinding support — bind a key to any extension command, or to a specific deck button via vscodeDeck.runButton.
• VSCode commands and shell commands in the same button, chained sequentially.
• Input prompts — ${input:branch} placeholders prompt the user when the button is clicked, turning one button into a parameterizable launcher.
• Real terminal for shell commands — full Ctrl+C support, interactive stdin, proper shell quoting on Windows and Unix.
• Parallel execution — each button press spawns its own named terminal; clicking again while one is running cancels it.
• Lazy terminal — buttons that run only VSCode commands (e.g. Save All) execute silently without opening a terminal.
• Collapsible categories — group related buttons under headers that remember their state across sessions.
• Overflow-scroll on hover — long titles automatically slide to reveal the rest when you hover.
• Workspace-aware auto-detection — a command scans every workspace folder (and each folder's immediate subdirectories) for recognized project types and generates a starter config.
• Multi-root workspace support — each workspace folder becomes its own category with the correct cwd injected.
• Flexible icons — emojis, image URLs, local paths, or inline SVG (with theme-aware currentColor support).

Installation

From the VS Code Marketplace — search for VSCode Deck in the Extensions sidebar (Ctrl+Shift+X) and click Install.

From source — clone, build, and launch the Extension Development Host:

git clone https://github.com/makaias/vscode-deck.git
cd vscode-deck
npm install

Open the folder in VSCode and press F5 — that launches an Extension Development Host window with the extension loaded. The Deck icon (a grid) appears in the Activity Bar.

As a .vsix package — for sideloading or sharing internally:

npm run package

That produces a .vsix you can install via Extensions: Install from VSIX… in the command palette.

code --install-extension vscode-deck-0.0.1.vsix

Getting started

1. Click the Deck icon in the Activity Bar (grid icon). The sidebar opens empty, with two buttons: Open visual editor and or edit JSON directly.
2. Three ways in:
   • Deck: Edit Buttons (Visual) — opens the drag-and-drop editor. Recommended for first-time users.
   • Deck: Generate Configuration from Workspace — scans your workspace and writes a starter .vscode/deck.json with buttons tailored to the tools it finds.
   • Deck: Edit Configuration — opens .vscode/deck.json directly. You'll get autocomplete, type-checking, and inline docs for every field.

The config file is watched — saves are picked up instantly, no reload required.

Configuration

The config lives at .vscode/deck.json (relative to the first workspace folder). Path is overridable via the vscodeDeck.configPath setting.

Editing deck.json directly triggers IntelliSense — autocomplete on mode, type, command, etc., red squigglies on typos, hover descriptions on every field, and an inline color picker for color. The bundled JSON schema is registered automatically; no setup required.

Minimal config

{
  "mode": "sidebar",
  "columns": 4,
  "buttons": []
}

Full example

{
  "mode": "sidebar",
  "columns": 4,
  "buttons": [
    {
      "title": "Save All",
      "icon": "💾",
      "commands": [
        { "type": "vscode", "command": "workbench.action.files.saveAll" }
      ]
    },
    {
      "title": "Maven Clean + Install",
      "icon": "📦",
      "color": "#d97706",
      "category": "Build",
      "commands": [
        { "type": "shell", "command": "mvn clean" },
        { "type": "shell", "command": "mvn install" }
      ]
    },
    {
      "title": "Dead Code",
      "icon": "🧹",
      "category": "Checks",
      "commands": [
        {
          "type": "shell",
          "command": "npm run knip",
          "continueOnError": true
        }
      ]
    }
  ]
}

Top-level fields

Button fields

Command step fields

Two step types, discriminated by type:

vscode — runs a VSCode command via executeCommand.

shell — runs a shell command.

Commands

Available from the command palette (Ctrl+Shift+P):

Visual editor

Run Deck: Edit Buttons (Visual) to open a dedicated editor — no JSON required.

• Drag-and-drop reorder: each button has a dotted handle on its left. Drag within a category to reorder, or drop into another category's section to recategorize. Empty categories show a drop zone.
• Categories: click + New category at the top to add one — it's named New category by default and the rename input auto-focuses. Each category has ▲▼ arrows to reorder, × to delete (its buttons move to Uncategorized after confirmation), and inline rename (renaming to an existing name merges; renaming to empty moves buttons to Uncategorized).
• Editing a button: click any card to expand it. Title, icon (with live preview), color (text input + native color picker), category (move-to dropdown), and commands list with add/delete/reorder per step.
• Save semantics: explicit save (Ctrl/Cmd+S or the Save button) — the editor's working copy is independent of the file on disk, so external edits don't fight live keystrokes. The header shows Unsaved changes / Saved status. Reload pulls the latest from disk, prompting if you have unsaved work.

Keyboard shortcuts

Every command and every deck button can be bound to a key.

Binding extension commands

Open File → Preferences → Keyboard Shortcuts (Ctrl+K Ctrl+S), search for Deck:, click the + next to any entry, and press your keys. All commands listed in the Commands table are bindable.

Binding individual buttons

The vscodeDeck.runButton command takes a button identifier as args:

{ "key": "ctrl+alt+b", "command": "vscodeDeck.runButton", "args": "Build" }

The match precedence is id first, then title. Set the optional id field on a button if you want the binding to survive title renames:

{ "title": "Build & Test", "id": "build", "commands": [...] }

For ambiguous titles (same title in different categories), use the object form:

{ "key": "ctrl+alt+t", "command": "vscodeDeck.runButton",
  "args": { "title": "Test", "category": "Backend" } }

If the target isn't found, you get an error toast naming the missing identifier.

The visual editor includes a Copy keybinding button per card that copies a ready-to-paste snippet to your clipboard — paste it into keybindings.json and fill in the "key" field.

Pressing the bound key while the button is already running cancels it (same click-to-cancel behavior as the deck UI).

Running state

While a button's commands are executing, the button shows a spinner with a dimmed icon, and its top border switches to the VS Code progress color and pulses. Hovering reveals a red stop square — clicking the running button kills the process tree (Windows: taskkill /T /F; POSIX: SIGTERM to the process group) and aborts the chain. The mechanism keys by button index, so triggering via keybinding lights up the right button when the deck view is open.

Icons

The icon field accepts any of these:

{ "icon": "💾" }

Emoji or plain text, rendered as-is.

{ "icon": "https://example.com/build.svg" }

URL to an image (http, https, or data: URI).

{ "icon": "./icons/build.png" }

Relative or absolute file path.

{
  "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"><path d=\"M12 5v14\"/><path d=\"M5 12h14\"/></svg>"
}

Inline SVG. Sized automatically to the configured icon size (default 28×28; override with the top-level iconSize field). For theme-aware icons, use fill="currentColor" (filled-style) or stroke="currentColor" with fill="none" (outline-style, e.g. Lucide, Feather, Tabler). Explicit colors in <path> are preserved.

Categories

Any button with a non-empty category goes into a collapsible section named after that category. Buttons without a category render first in a flat grid above all sections.

{
  "buttons": [
    { "title": "Save All", "icon": "💾", "commands": [...] },
    { "title": "Build",    "icon": "🔨", "category": "Maven", "commands": [...] },
    { "title": "Install",  "icon": "📦", "category": "Maven", "commands": [...] },
    { "title": "Test",     "icon": "🧪", "category": "NPM",   "commands": [...] }
  ]
}

Renders as:

[Save All]

▾ MAVEN
  [Build]   [Install]

▾ NPM
  [Test]

Click a category header to collapse/expand it. The collapsed state is remembered per-category across config edits and window reloads.

Auto-detection: Deck: Generate Configuration from Workspace

Running the generate command scans the workspace and produces buttons for every project type it recognizes. Each scanned directory becomes its own category with the correct cwd injected.

What it scans

1. Every workspace folder in the current workspace (supports multi-root workspaces).
2. Each folder's immediate subdirectories (skipping node_modules, dist, target, .git, .venv, etc.).

Recognized project types

Example: multi-root workspace

root-workspace.code-workspace
├── frontend/      (package.json, Vue.js)
├── coordinator/   (pom.xml, Java)
└── autogluon/     (pyproject.toml, Python)

After running the generate command, you get categories:

• General (uncategorized Save All / Format / Terminal / Command Palette)
• Git
• frontend — npm install plus one button per script in frontend/package.json, each with cwd: "${workspaceFolder:frontend}"
• coordinator — Maven lifecycle buttons, each with cwd: "${workspaceFolder:coordinator}"
• autogluon — pytest / Black / Ruff / pip install, each with cwd: "${workspaceFolder:autogluon}"

Safety

• The command never overwrites without asking. If deck.json already has buttons, you get a modal confirmation before they're replaced.
• mode and columns from your existing config are preserved.
• Your workspace files are never modified — only .vscode/deck.json.

Shell command details

Where output goes

Each button press spawns a named terminal like Deck: Maven Clean + Install. Output streams live, exactly as if you'd typed the command. Interactive commands (anything that reads stdin) work.

Ctrl+C

Focus the terminal and press Ctrl+C — sends SIGINT to the running process and its entire process tree (so npm run build doesn't leave an orphan node compiler behind). On Windows this uses taskkill /T /F; on Unix it signals the process group.

When cancelled, the exit code is non-zero and the chain aborts (unless continueOnError: true).

Chain abort behavior

If a shell step exits non-zero, later steps in the same button don't run. The terminal shows:

[exit 1]
! exited with code 1; aborting chain

Except:

• When the failing step is the last step, the "aborting chain" line is suppressed (there's nothing to abort).
• When the step has continueOnError: true, a non-zero exit is accepted and the next step runs anyway.

Working directory

cwd supports two VSCode-style placeholders:

• ${workspaceFolder} — the first workspace folder.
• ${workspaceFolder:<name>} — a specific folder by name in a multi-root workspace.

You can also combine them with subdirectory paths: "cwd": "${workspaceFolder:frontend}/packages/app".

Shell quoting

Shell commands run via child_process.spawn with shell: true, which on Windows invokes cmd.exe /d /s /c "<command>" — the /s flag preserves inner quotes correctly for command lines with multiple quoted paths, e.g.:

{ "type": "shell", "command": "\"C:\\tools\\mvn\\bin\\mvn\" install -f \"C:\\Projects\\app\\pom.xml\"" }

Input prompts

Any string field (shell command, shell cwd, or any string inside vscode args) can contain ${input:<name>} placeholders. When you click the button, Deck prompts for each unique input upfront, then runs the chain with the values substituted.

Syntax

If you press Escape on any prompt, the entire chain aborts cleanly — no commands run, no status dot appears.

Examples

Prompt for a branch when checking out:

{
  "title": "Checkout branch",
  "icon": "🌿",
  "commands": [
    { "type": "shell", "command": "git checkout ${input:branch:main}" }
  ]
}

Prompt for a port and use it both in the dev server and the browser-open command:

{
  "title": "Dev (custom port)",
  "icon": "▶️",
  "commands": [
    { "type": "shell", "command": "npm run dev -- --port ${input:port:3000}" },
    { "type": "vscode", "command": "vscode.open", "args": ["http://localhost:${input:port:3000}"] }
  ]
}

Prompt for a commit message before committing:

{
  "title": "Commit",
  "icon": "💬",
  "commands": [
    { "type": "shell", "command": "git commit -m \"${input:message}\"" }
  ]
}

Multi-input chain (release tag flow):

{
  "title": "Tag release",
  "icon": "🏷️",
  "commands": [
    { "type": "shell", "command": "git tag -a ${input:version} -m \"${input:notes}\"" },
    { "type": "shell", "command": "git push origin ${input:version}" }
  ]
}

Example recipes

Save and format in one click

{
  "title": "Save & Format",
  "icon": "✨",
  "commands": [
    { "type": "vscode", "command": "editor.action.formatDocument" },
    { "type": "vscode", "command": "workbench.action.files.saveAll" }
  ]
}

Maven clean-install for a monorepo subfolder

{
  "title": "Coordinator: CI",
  "icon": "📦",
  "category": "Coordinator",
  "commands": [
    { "type": "shell", "command": "mvn clean", "cwd": "${workspaceFolder:coordinator}" },
    { "type": "shell", "command": "mvn install", "cwd": "${workspaceFolder:coordinator}" }
  ]
}

Lint that only warns, never fails

{
  "title": "Lint",
  "icon": "📎",
  "commands": [
    {
      "type": "shell",
      "command": "npm run lint",
      "continueOnError": true
    }
  ]
}

Dev server in the frontend subfolder

{
  "title": "Frontend Dev",
  "icon": "▶️",
  "category": "frontend",
  "commands": [
    {
      "type": "shell",
      "command": "npm run dev",
      "cwd": "${workspaceFolder}/frontend"
    }
  ]
}

Open a specific tool's sidebar

{
  "title": "Source Control",
  "icon": "🌿",
  "commands": [
    { "type": "vscode", "command": "workbench.view.scm" }
  ]
}

Build + test + deploy chain

{
  "title": "Ship It",
  "icon": "🚀",
  "color": "#10b981",
  "commands": [
    { "type": "shell",  "command": "npm run build" },
    { "type": "shell",  "command": "npm test" },
    { "type": "shell",  "command": "npm run deploy" },
    { "type": "vscode", "command": "workbench.action.terminal.focus" }
  ]
}

If build or tests fail, deploy doesn't run — the chain aborts with the failing step's exit code.

Settings

Finding VSCode command IDs

To find the ID of a VSCode command (for "type": "vscode" steps):

1. Keyboard Shortcuts: Ctrl+K Ctrl+S, search for the action, right-click → Copy Command ID.
2. Commands palette source: some extensions list their commands in package.json; browsing an extension's source on GitHub shows them under contributes.commands.
3. Running extensions: Ctrl+Shift+P → Developer: Show Running Extensions to confirm an extension is loaded and inspect its namespace.

Common built-in IDs:

• workbench.action.files.saveAll
• workbench.action.files.save
• editor.action.formatDocument
• workbench.action.terminal.new
• workbench.action.terminal.toggleTerminal
• workbench.action.showCommands
• workbench.view.explorer / workbench.view.scm / workbench.view.debug
• workbench.action.reloadWindow
• git.pull / git.push / git.sync / git.commit

Limitations

• Buttons are a flat list within each category — no nested sub-categories.
• Auto-detection scans the workspace root and one level of subdirectories. Nested projects (e.g. frontend/packages/app) require manual configuration.
• The config lives in the first workspace folder's .vscode/ even in multi-root workspaces (matching the VSCode convention for tasks.json and launch.json).
• Shell step quoting follows Node's child_process.spawn({ shell: true }) rules. On Windows this is cmd.exe /d /s /c. If you need a different shell, wrap explicitly, e.g. "command": "pwsh -c \"Get-Process\"".

License

MIT.