Getting started

This guide takes you from a fresh install to your first clickable command.

Why I built this

Monorepos are my bittersweet ally. Every package brings its own scripts, and I never could keep them straight. I kept retyping the same commands, wasting time.

Buttons is my marriage counsellor. It scans the scripts, turns them into buttons, and remembers what I don’t want to. That’s what makes my monorepos tolerable.

1. Install

Install Buttons for your editor:

• VS Code: Install from the Marketplace
• VSCodium: Install from Open VSX

2. Open a project

Open a folder in VS Code that contains scripts. Any project with a package.json, Cargo.toml, go.mod, shell scripts, Python entry files, a Makefile, composer.json, or justfile works.

3. Open Buttons

Click the Buttons icon in the Activity Bar on the left, or the Buttons icon in the editor title bar (top-right, near “split editor”). Both open the same launcher and stay in sync.

4. Generate your buttons file

Opening a project never writes anything on its own. Click Generate in the Project scripts tab to scan the project and create a .buttons.json file with every root-level discovered script.

Note

Generate creates the file the first time. Click it again later to add any missing root-level scripts; custom commands and your edits stay. Rescan refreshes commands for scripts you already have. See Generate vs Rescan.

On a fresh project, the Project scripts tab shows every discovered script with its checkboxes disabled until you generate the file.

5. Fine-tune

• In the Project scripts tab, uncheck scripts you don’t want, or check newly-discovered ones.
• Scripts outside the project root? Add their directories in the Scan directories card, and make them recursive for monorepo packages. See Script scanning.
• In the Buttons tab, add custom commands with + Add command, or add notes to any row.
• The markdown icon in the header copies the Buttons AI skill, or writes BUTTONS-SKILL.md so an agent can create .buttons.json for you.

See Using Buttons for details.

6. Run a command

Switch to the Buttons tab. Each row gives you:

• Run: run in the current integrated terminal.
• New Terminal: run in a fresh terminal named Buttons: <label>.
• System: open the OS terminal at the project root with the command ready. Press Enter to run.
• Copy: copy the exact command to the clipboard.

The working directory is set to the script’s folder, so a script in a monorepo package runs in the right place.

Next steps

• Using Buttons: the two tabs and two surfaces in detail.
• Custom commands: add commands that aren’t in a script file.
• FAQ: common questions about scanning, storage, and Rescan.
• Troubleshooting: empty panels, missing scripts, and parse errors.