Using Buttons

Buttons has two tabs and can be opened in two places. Everything stays in sync, so you can use both surfaces at once.

Two ways to open it

• Activity Bar: click the Buttons icon in the left Activity Bar for a compact sidebar. The window icon in the header (and on the sidebar title bar) opens the full editor panel.
• Editor panel: click the Buttons icon in the editor title bar (top-right, near “split editor”) for a full-width editor tab. The tab shows the Buttons logo.

The sidebar renders each button as a compact card (command and note on one row, actions on the next). The editor panel renders the full table: Command | Note | Actions. Drag the edges of those column headers to resize them. Widths persist while the panel is open.

The markdown icon in either header copies the Buttons AI skill to the clipboard, or writes BUTTONS-SKILL.md at the project root so coding agents can create a complete .buttons.json. If the file already exists, Buttons asks before replacing it.

The Buttons tab

The default tab shows two sections:

• Project buttons: commands from the current workspace’s <workspace root>/.buttons.json.
• Global buttons: commands from your personal ~/.buttons.json, shown in every project.

Each row (or card, in the sidebar) shows the command, an optional note, a file badge for script buttons, and the action buttons described below.

The Project scripts tab

A list of every discovered script. Checking a box adds it as a project button; unchecking removes it. Changes are saved immediately once the file exists.

The tab also holds the Scan directories card, which lists extra directories on top of the always-scanned project root (top level only). Each row has a recursive toggle. Type or paste a path into the Add field: relative paths resolve inside the project, full paths reach outside it. The card edits the buttons.scanDirectories workspace setting.

In the Explorer, right-click a .sh or Python entry file and choose Add to Buttons to add it as a standalone project button without scanning its folder. Right-clicking a manifest (package.json, Makefile, justfile, composer.json, Cargo.toml, go.mod) adds that folder as a scan directory.

Detected virtual environments (venv/ or .venv/) appear here too, grouped under the venv’s path. See virtual environments.

Before you Generate a file, the boxes are disabled and a Generate buttons file call-to-action is shown instead.

Run, copy, and manage

Every button gives you:

• Run: run in the current integrated terminal (reusing the active terminal if one is open, otherwise a terminal named Buttons).
• New Terminal: run in a fresh terminal named Buttons: <label>.
• System: open the configured OS terminal at the project root with the command already on the prompt. Does not run. Press Enter in that terminal to run.
• +: add the command to the current terminal line with a space (pnpm then dev → pnpm dev). Does not run.
• ↵: add the command on a new line. Does not run. Press Enter in the terminal when the line is ready.
• Copy: copy the exact command to the clipboard.
• Duplicate: clone the button (and its variants) as a new row.
• Note / Edit: inline-edit the note (for script buttons) or the command/args and note (for custom commands and args variants).
• ✕: first click shows Confirm; click again to remove.

Drag the gripper to reorder siblings; the order is saved in .buttons.json.

Parents with a chevron expand to parameter options (children) and + Add variant, which appends extra args to that row’s live command. Variants can nest: a variant has its own chevron and + Add variant. A badge next to the chevron shows how many variants the parent has and stays visible while the group is open. If those variants have children of their own, the badge is direct:deeper (two children that themselves hold five more rows is 2:5). Open groups pick up a depth color from the current theme on the chevron, row border, and badge. Child command chips and + Add variant use that group’s color. Opening a nested variant keeps that row in the parent color; the new color is for the children it adds. The parent’s Run still runs the base command.

Script buttons with a missing reference (the script no longer exists in the scan) are shown but cannot be run. See Troubleshooting.

Configurable text size and colors

Set the UI text size to VS Code default, +2px, or +4px via buttons.textSize. Optional buttons.colors.* hex values tint each action button, command text and background, variant commands, and odd/even rows; leave them empty to inherit VS Code’s current color theme. The gear icon in the panel header jumps to Buttons settings. See Configuration.

To add a command that isn’t in a script file, see Custom commands.