pls mode

pls mode is a small VS Code extension that turns a repo's everyday terminal commands into a friendly local cockpit: clear labels, copy buttons, run buttons, and confirmation for risky commands.

Status: public beta candidate. The core flow builds, tests, packages, and installs locally; Marketplace publishing still needs the final publisher confirmation and a real Extension Development Host screenshot pass.

pls mode makes the boring commands visible where the work already happens, while VS Code's terminal still does the running.

What This Is Not

• Not a terminal replacement, task runner, CI system, or workflow automation engine.
• Not a remote command runner, secret manager, shell-profile manager, or team policy product.
• Not a big serious enterprise platform. It is a useful little button panel that knows its lane.

Why It Exists

This was one of the first tools I made when I started my coding journey. It came from roughly 50% need, 50% laziness, 50% curiosity about making IDE extensions, and maybe 2% bad math skills.

The need was simple: most projects have a handful of commands everyone keeps looking up. Start the app. Run the tests. Build the package. Reset the local output. New people need a setup tour, future-you forgets the exact spellings, and agents benefit from seeing the safe path instead of guessing.

pls mode lets each repo describe those commands in .plsmode.json, then shows them as plain-language actions in VS Code.

Quick Start

The Marketplace release is not published yet. For now, run it from source or build a local VSIX.

corepack enable
pnpm install --frozen-lockfile
pnpm verify

Press F5 in VS Code to launch an Extension Development Host.

To try it like a user:

pnpm package
code --install-extension plsmode-0.0.1.vsix

Create .plsmode.json in a workspace root:

{
  "version": 1,
  "terminalName": "pls mode",
  "categories": [
    {
      "id": "daily",
      "title": "Daily",
      "items": [
        {
          "id": "install",
          "label": "Install dependencies",
          "cmd": "pnpm install --frozen-lockfile",
          "description": "Downloads the exact packages this project expects"
        },
        {
          "id": "test",
          "label": "Run tests",
          "cmd": "pnpm test",
          "description": "Checks that the project still works"
        },
        {
          "id": "clean-output",
          "label": "Clean generated output",
          "cmd": "rm -rf out",
          "danger": true,
          "confirm": "This deletes compiled extension output. Continue?",
          "description": "Removes generated files so the next compile starts fresh"
        }
      ]
    }
  ]
}

Open the pls mode panel in the VS Code sidebar and click a command. Use copy when you want to inspect or learn the command before running it.

Starter configs:

• docs/examples/minimal.plsmode.json - the smallest useful first-run config.
• docs/examples/rich.plsmode.json - categories, subcategories, and a dangerous command example.

Features

• Repo-local command panel - each workspace owns its own .plsmode.json.
• One-click terminal execution - safe commands can be sent to VS Code's integrated terminal.
• Copy before running - useful for learning, inspecting, or pasting manually.
• Dangerous command confirmation - commands marked with danger: true ask first.
• Clear empty/error states - missing and invalid config files get different help.
• Starter marketplace - add common npm, pnpm, Git, Docker, test, and cleanup commands while preserving safety metadata.

Safety Model

Configured commands come from the current workspace, so review unfamiliar .plsmode.json files like you would review scripts.

• Commands do not run automatically.
• Terminal execution is blocked when VS Code marks the workspace as untrusted.
• Dangerous commands need an explicit confirmation click.
• pls mode does not store credentials and .plsmode.json should not contain secrets.

Configuration Reference

Command item:

Property	Type	Required	Description
id	string	Yes	Unique identifier for the command
label	string	Yes	Display name shown in the UI
cmd	string	Yes	Terminal command to execute or copy
description	string	No	Helpful explanation of what the command does
danger	boolean	No	If true, asks before running
confirm	string	No	Custom confirmation text for dangerous commands

Category:

Property	Type	Required	Description
id	string	Yes	Unique category identifier
title	string	Yes	Display name for the group
items	array	No	Command objects
subcategories	array	No	Nested command groups

Each category needs at least items or subcategories.

Development

corepack enable
pnpm install --frozen-lockfile
pnpm compile
pnpm test
pnpm package

Use pnpm verify before publishing or sending a pull request. It runs compile and tests.

The shipped VSIX should contain compiled JavaScript, public docs, examples, and visual assets only. Source files, tests, reports, archives, local assistant files, and local VSIX packages are excluded by .vscodeignore.

Public Beta Checklist

• Position pls mode as a repo-local project cockpit, not a generic launcher.
• Preserve dangerous-command metadata from marketplace commands.
• Separate missing-config and invalid-config states.
• Block terminal execution in untrusted or missing workspaces.
• Add first-run examples, contribution notes, security notes, and visual publication assets.
• Add a local verify command and CI workflow.
• Confirm final Marketplace publisher value.
• Capture real VS Code screenshots/GIF from the Extension Development Host before the first public tag.

Contributing

Contributions are welcome during beta prep, especially fixes that make setup, config loading, command safety, or documentation clearer. Please keep changes small and easy to review. See CONTRIBUTING.md.

Security

To report a security issue, see SECURITY.md.

License

MIT

---

Made with care for people who want the helpful commands close at hand and do not want to memorize pnpm-whatever-it-was again.