Runpalette

One command palette for every project — and every coding agent.

Turn package scripts, Justfiles, Taskfiles, Make targets, Cargo aliases, and Gradle tasks into one searchable, MCP-native command surface for developers, coding agents, and CI.

Quick start · What it does · Agents & MCP · How it works · Documentation

Quick start

Try Runpalette without changing the project:

npx runpalette

Runpalette finds the nearest supported project, discovers the commands it already owns, and opens an immediate type-to-search palette. Nothing needs to be copied into the target project and Runpalette does not introduce a new task format.

Install it for the whole team and expose the short project-local command:

npm install --save-dev runpalette

{
  "scripts": {
    "what": "runpalette"
  }
}

The same package can be installed with pnpm add -D runpalette, yarn add -D runpalette, or bun add -d runpalette.

What Runpalette does

• Find the project — walk upward from the current directory or an explicit --cwd to package, Just, Task, Make, Cargo, or Gradle project metadata.
• Unify existing tools — combine every discovered command into one catalog without replacing the tool that owns execution.
• Make commands scannable — group existing commands into development, quality, build/release, data/operations, and a conservative fallback group.
• Understand workspaces — discover root and package scripts across npm, pnpm, Yarn, and Bun monorepos, then run from the selected package directory.
• Search immediately — type any part of a command name or implementation; press Tab to focus a group, then use arrows or Ctrl-N / Ctrl-P to move.
• Complete in your shell — generate Bash, Zsh, Fish, or PowerShell completion with live project command and alias candidates.
• Describe your workflows — add labels, descriptions, aliases, ordering, custom groups, defaults, hidden entries, and explicit confirmation without replacing the commands your project already owns.
• Check command prerequisites — declare required environment names and external executables, inspect readiness before launch, and fail early instead of discovering missing setup halfway through a workflow.
• Bootstrap configuration safely — create a schema-linked team config and validate it against the commands the repository actually exposes.
• Show the exact action — keep the owning source, delegated command, and underlying implementation visible while selecting.
• Diagnose readiness — validate command discovery, package-manager availability, configuration, and optional source tooling with one human- or machine-readable check.
• Delegate faithfully — let the original package manager or task tool own local binaries, lifecycle behavior, arguments, and exit codes.
• Serve agents and automation — expose the same catalog and execution plans as versioned JSON, run tasks with bounded structured output, or use read-only-by-default MCP tools.

Choose how you work

From your terminal

Open the palette from anywhere inside a project:

runpalette

Or skip the interface when you already know the script:

runpalette list
runpalette list --workspace @acme/web
runpalette list --group quality
runpalette list --source make
runpalette doctor
runpalette config init
runpalette config validate
runpalette completion zsh
runpalette run test:unit
runpalette run verify --source make
runpalette run dev --workspace @acme/web
runpalette run test:unit -- --watch
runpalette run build --dry-run

The dry-run explains where the command came from, which workspace and directory it uses, whether confirmation is required, whether declared prerequisites are available, and the exact invocation—without executing project code.

The palette uses an alternate terminal screen and restores the normal terminal before the selected task starts. The child then receives ordinary stdin, stdout, and stderr instead of running inside a simulated console.

Learn the keyboard and command surface →

For an optional team-owned command surface, run runpalette config init, edit the generated runpalette.json, then check it with runpalette config validate. Monorepos require no Runpalette configuration; see the workspace guide for selection and ambiguity behavior.

For agents and automation

Give a coding agent or CI job a stable inventory instead of asking it to infer commands from README prose or execute an unknown shell string:

runpalette list --json
runpalette doctor --json
runpalette run test:e2e --dry-run --json
runpalette run test:e2e --json --timeout 2m

--json implies non-interactive behavior and writes one versioned result to stdout. Diagnostics stay on stderr. A dry run returns the exact executable, argument array, working directory, selected command, and source choice without executing the task.

For CI and agents, actual JSON execution captures stdout and stderr into one bounded result while preserving exit status, timing, timeout, cancellation, and truncation metadata. Captured execution disables stdin; use human stream mode for an interactive task. Human execution keeps the task's native streams:

runpalette run verify --non-interactive

Or expose the catalog and exact execution plans directly over MCP:

runpalette mcp

The MCP server offers check_project, list_commands, and plan_command by default, so an agent can verify readiness before selecting work. run_command exists only when the user explicitly starts the server with --allow-execution; configured confirmations still apply to every call and execution is time/output bounded. Plans expose declared command requirements; execution refuses a command whose required environment names or executables are unavailable.

Connect a coding agent with MCP →

One project. One command surface.

start anywhere inside a project
        ↓
find the nearest supported project source
        ↓
discover commands through source-owned metadata
        ↓
normalize and group one source-aware catalog
        ↓
search or select one exact command
        ↓
preview the execution plan or delegate it unchanged

• Automatic install and publishing hooks stay out of the default palette.
• Unknown commands remain visible instead of being silently discarded.
• Conflicting lockfiles produce a warning and deterministic selection.
• Command names and metadata are sanitized before terminal rendering.
• No-argument use outside a TTY prints a deterministic plain catalog and never attempts to prompt.
• NO_COLOR, TERM=dumb, ASCII rendering, narrow terminals, and explicit non-interactive operation have first-class paths.

Keep your existing stack

Command sources	Package managers	CLI runtime	Interfaces
package scripts · Just · Task · Make · Cargo aliases · Gradle	npm · pnpm · Yarn · Bun	Node.js 22+ · Bun 1.3 · Deno 2.9	interactive TTY · text · JSON · MCP

Package-manager choice is independent from the runtime executing Runpalette. The stable 1.x release contract covers Node.js, Bun, and Deno only after the packed CLI passes discovery, diagnostics, planning, execution, completion, and MCP checks under each.

See current compatibility evidence →

Predictable by default

• Runpalette constructs an executable plus argument array; it does not build a shell command around your selection.
• The detected project root becomes the task working directory.
• Source-specific argument separators are added only where required.
• A missing command or owning executable returns an actionable error.
• Machine output is schema-versioned, prompt-free, and free of ANSI styling.
• Marketing media, private product research, fixtures, and development context are excluded from the npm artifact.
• The packaged-consumer check installs the generated tarball into a clean project and launches the installed CLI before verification can pass.

Documentation

Guide	Start here when you want to…
CLI guide	Diagnose readiness, search, run commands, pass arguments, or use JSON.
Shell completion	Complete Runpalette options and current project commands in your shell.
Command sources	Understand discovery and native execution for each project tool.
MCP and agents	Connect an agent, inspect plans, or enable bounded execution.
Configuration	Name, group, order, protect, hide, alias, or default commands.
Workspaces	Use Runpalette in npm, pnpm, Yarn, or Bun monorepos.
Compatibility	Check runtimes, package managers, terminals, and support status.
Stability	Understand the 1.x CLI, config, JSON, MCP, and exit-code contract.
Changelog	Review user-visible additions and behavior changes.
Contributing	Set up the repository and prepare a focused change.
Security	Report a vulnerability privately and review the support policy.

Run runpalette --help for the complete command and option reference.

Sponsors

Runpalette is independently developed and maintained. Sponsorship helps fund compatibility testing, CI, documentation, maintenance, and dependable releases across supported project tools and runtimes.

Sponsor Runpalette and my open-source work →

Project

Changelog · Contributing · Security · CLI guide · MIT License

Runpalette is a discovery and launch layer over commands your project already owns. It is not another package manager, task format, or build system.