# 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

**Related:** [repositories-and-worktrees](repositories-and-worktrees.md) · [terminal](terminal.md) · [settings](settings.md) · [keyboard-shortcuts](../reference/keyboard-shortcuts.md)

## 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](command-palette.md). 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`](cli.md)).