Custom Actions, Scripts & Run Commands #

Turn repeated commands into buttons and hotkeys: the Run Script, the automatic Setup/Archive scripts, and global or per-repo Custom Commands.

Keywords: custom command, custom action, run script, setup script, archive script, button, hotkey, PROWL_WORKTREE_PATH, PROWL_ROOT_PATH, close on success, split, terminal input, swift build, npm test, claude -p

Overview #

Prowl has four distinct mechanisms for "run my command":

Mechanism	Scope	When it runs	Configured in
Run Script	one per repo	on demand (`⌘R`)	Repo Settings → Run Script
Setup Script	one per repo	automatically after a worktree is created	Repo Settings → Setup Script
Archive Script	one per repo	automatically before a worktree is archived	Repo Settings → Archive Script
Custom Commands	many, global or per repo	on demand (button / hotkey / palette)	Settings → Commands or Repo Settings → Custom Commands

All scripts run with these environment variables injected:

PROWL_WORKTREE_PATH — the active worktree's directory.
PROWL_ROOT_PATH — the repository root.

Run Script (`⌘R` / `⌘.`) #

A single per-repo command you launch on demand.

Run: ⌘R (run_script) — runs the repo's Run Script in the focused worktree. If no Run Script is set, you're prompted for one.
Stop: ⌘. (stop_script).
A toolbar Run button is shown when showRunButtonInToolbar is on.
While running, the worktree shows a running status; the tab is title-locked to the command until it finishes.

Setup Script (automatic on create) #

Set a per-repo Setup Script to bootstrap every new worktree — install deps, copy env files, warm caches, etc. It runs automatically right after worktree creation, in the new worktree, with PROWL_WORKTREE_PATH / PROWL_ROOT_PATH set.

Archive Script (automatic on archive) #

A per-repo Archive Script runs before a worktree is archived — tear down servers, clean artifacts, etc. If it exits non-zero, archiving stops and the worktree stays active, with the error shown.

Custom Commands (buttons + hotkeys) #

The most flexible option: define multiple named actions globally or per repository, each with its own SF Symbol icon, shell command, execution mode, optional close on success, and optional keyboard shortcut.

Execution modes:

Mode	What it does	Supports "close on success"
Shell script	runs in a new terminal tab	✅
Terminal input	types the command into the focused pane	❌
Split	runs in a new split of the focused pane (direction: right/left/down/top)	✅

Close on success auto-closes the tab/split shortly after the command exits 0 (a brief delay lets you see the final output).

Visibility and order: local and Global commands both appear, even when their titles match. Enabled local commands appear first in their repository order, followed by enabled Global commands in their Global order. Turning a command off preserves its configuration, position, and hotkey, but removes it from the toolbar, Worktrees menu, Command Palette, and hotkey dispatch until re-enabled.

Global gates: a Global command appears in a repository only when it is enabled globally and enabled for that repository. New Global commands are enabled in every repository by default; Repo Settings can turn an individual Global command off without changing its definition. Global command fields and order are edited only in Settings → Commands.

Shortcut precedence: a repo command wins a collision with a Global command's shortcut. Custom Command hotkeys take precedence over app shortcuts; conflicts (with reserved app actions or other custom commands) are detected when you record the key, and you choose Replace / Cancel.

Where they appear: enabled commands appear in the window toolbar, the Worktrees menu, and the Command Palette. Global commands are stored in ~/.prowl/global.onevcat.json; local commands remain in ~/.prowl/repo/<repo-name>/prowl.onevcat.json.

Example uses #

swift build on ⌘B (shell script).
npm run dev as a split that stays open (split mode, no close-on-success).
claude -p "review the current diff and summarize risks" (shell script) — a one-keystroke AI assistant.
git push && gh pr create --fill on a hotkey.

Settings recap #

Per repo (Repo Settings): runScript, setupScript, archiveScript, local Custom Commands, and per-repository visibility of Global Commands.
Global (Settings → Commands): Global Custom Commands and their order.
Global: showRunButtonInToolbar, showDefaultEditorInToolbar.

Gotchas for agents #

The three named scripts (runScript/setupScript/archiveScript) are one each per repo; Custom Commands are the "many" option at either scope.
Scripts always have PROWL_WORKTREE_PATH and PROWL_ROOT_PATH available — use them instead of assuming a working directory.
"Terminal input" mode types into whatever pane is focused — be sure of the target (the same caution as prowl send).