# Settings

> Workflow UI is enabled by default. Start Prowl with `PROWL_WORKFLOW_UI=0` to hide its UI and skill row; CLI workflow and skill commands remain available. The switch is read at process startup.

> The Settings window (`⌘,`): what each tab controls. For the exhaustive
> field-by-field list, see [`reference/settings-fields.md`](../reference/settings-fields.md).

**Keywords:** settings, preferences, ⌘comma, general, notifications, shortcuts, worktree, updates, advanced, github, agents, agent profiles, workflows, workflow settings, enable workflow, bindings, cli & skills, command line tool, cli, socket status, agent skills, skills install, repo settings, appearance

**Related:** [reference/settings-fields](../reference/settings-fields.md) · [custom-actions](custom-actions.md) · [updates](updates.md) · [notifications](notifications.md) · [workflows](workflows.md)

## Opening

`⌘,` (`open_settings`), the app menu, or Command Palette → "Open Settings". The
window is a native macOS split window: the sidebar selects top-level sections,
and its toolbar's sidebar control can hide or show that sidebar. Re-opening
Settings brings the existing Settings window forward rather than creating
another one. `⌘W` closes it.

Most sections are roots in the detail pane. A section can drill in without
losing the sidebar; for example, **Agents → Profiles** → a profile pushes its
editor and macOS shows the standard Back control beside the editor title. Back
returns to Profiles, while selecting another sidebar item leaves the drill-in
and opens that section's root.

## Sections

| Section | Controls |
|-----|----------|
| **General** | Application language (Follow System, 简体中文, English; the same per-app setting as System Settings → Language & Region → Applications; takes effect on next launch), appearance (system/light/dark), terminal config (share Ghostty's config files or use a dedicated file; Open Config, Reload), default app for opening worktrees, diff tool, confirm-before-quit, default view mode, restore terminal layout on launch + clear saved layout, window chrome tint, automatic repository icon detection, toolbar buttons (Run / Open-in-editor), dim unfocused splits. |
| **Notifications** | In-app alerts, notification sound picker (Never / system sounds / Prowl Classic), macOS system notifications, move-notified-to-top, command-finished notification + threshold, Dock badge & bounce. → [notifications](notifications.md) |
| **Shortcuts** | Remap app keyboard shortcuts; view defaults; resolve conflicts. → [keyboard-shortcuts](../reference/keyboard-shortcuts.md) |
| **Worktree** | Worktree creation/deletion defaults: prompt on create, fetch before create, base directory, copy ignored/untracked files, automatic local-branch cleanup, merged-worktree action, archived auto-delete period (asks for confirmation when the new period would delete archived worktrees right away). |
| **Updates** | Auto-check toggle, "Check for Updates Now". → [updates](updates.md) |
| **GitHub** | Enable GitHub integration (uses the `gh` CLI). → [github-pull-requests](github-pull-requests.md) |
| **Commands** | Global Custom Commands. Enabled commands appear in the window toolbar; each repo can independently hide a Global command. → [custom-actions](custom-actions.md) |
| **Advanced** | Analytics, crash reports. |
| **Agents → Display** | Active Agents panel auto-show, terminal titles, Shelf status markers, and Agent Island enablement, Monitor, global shortcut, silent opacity, and floating-position reset, and **Detect agents in SSH sessions** (Prowl's own SSH connection; asked at the first `ssh`). → [active-agents](active-agents.md), [agent-island](agent-island.md), [agent-detection](agent-detection.md#remote-agents-over-ssh) |
| **Agents → Profiles** | Named launch presets for supported agent runtimes (model, effort, execution mode, tab/split placement, extra arguments, opt-in dedicated home for a separate account) with a live launch preview. List order is the recommendation fallback. → [agent-profiles](agent-profiles.md) |
| **Agents → CLI & Skills** | Install/status for the bundled `prowl` CLI, the local socket path it uses to reach the app and whether this app is **listening** on it, and the **Agent Skills** section that links the bundled skills into your agents' skill folders. → [cli](cli.md) |
| **Agents → Workflows** | Compact Built-in and personal workflow lists. Select a row for Enabled, explicit Run target, role profile preferences, Run Setup, validation, and source-file actions; **New Workflow…**, **Create with Agent…**, the **Run History** summary with **Clear History…**, and the CLI dependency banner remain on the index. → [workflows](workflows.md) |
| **Repositories / Repo Settings** | Per-repository: setup/archive/run scripts, **Custom Commands**, Global-command visibility, **Default Agent Profile**, a direct **Workflows** list, default base ref & directory, copy-files overrides, open-with app, custom title, icon & color, PR merge strategy, line-diff & PR-state fetching. Reached from the sidebar context menu → "Repo Settings". A workspace's page also shows its metadata with an **Edit Workspace…** button that opens the editor on the main window. → [custom-actions](custom-actions.md), [repositories-and-worktrees](repositories-and-worktrees.md), [workflows](workflows.md), [workspaces](workspaces.md) |

## Where settings live on disk

- **Global:** `~/.prowl/settings.json`
- **Global custom commands + agent profiles + workflow settings:** `~/.prowl/global.user.json`
- **Your workflow files:** `~/.prowl/workflows/*.pwlworkflow` (per repository: `<repo root>/.prowl/workflows/*.pwlworkflow`)
- **Per-repo:** `~/.prowl/repo/<repo-name>-<hash>/prowl.json`
- **Per-repo custom commands + agent profile default/memory:** `~/.prowl/repo/<repo-name>-<hash>/prowl.user.json`
- **Dedicated agent profile homes:** `~/.prowl/agent-profiles/<uuid>/`

`<hash>` is the first 8 hex digits of the SHA-256 of the repository path. Earlier
versions used `~/.prowl/repo/<repo-name>/`, which two repositories with one name
shared; Prowl copies those files (and reads those icons in place) on first use and
never deletes them. A symlinked file (for example, from dotfiles) is copied as a link to
the same target, so repositories that shared it keep sharing it. Settings follow the
path: a moved repository loads the copy source again, not edits made at its old path.

Legacy `~/.supacode` is migrated to `~/.prowl` on first launch. Old `.onevcat.json`
user settings migrate without deleting the source. See the
[migration and recovery rules](../reference/settings-fields.md#user-settings-migration).

## Install the CLI from here

**Agents → CLI & Skills → Install** symlinks `prowl` into `/usr/local/bin`
(prompting for admin rights if needed). Also available via Command Palette →
"Install Command Line Tool". See [cli](cli.md).

The page's **Connection** section shows the socket path and a **Status** row:
**Listening** (this app accepts `prowl` connections), **Not listening** with the
reason (another Prowl instance already owns the socket — quit it or give this
instance its own `PROWL_CLI_SOCKET`; a permission or path-length problem), or
**Not running**. The same reason blocks Run in the workflow start sheet and tops
the Workflows page, since workflow participants deliver through `prowl`.

## Workflows

**Agents → Workflows** lists Built-in and personal workflows; repository
workflows appear in the matching Repository Settings immediately after
**Agents**. Select any compact row for **Enabled**, **Run in <worktree>**, every
role's behavior, **Preferred Agent Profile** for launch roles, **Run Setup**
(Follow Workflow / Always Review Before Running / Run Directly When Possible),
validation, and source-file actions. **New Workflow…** asks for a name, id,
icon, and a single- or multi-agent starter, then opens the YAML in the default
app; **Create with Agent…** provides an authoring prompt, including a valid
creation draft when opened from that form. **Manage Workflows…** in the Agents
capsule opens this Settings page directly. **Run History** shows
the archive size with **Clear History…**. Rows and open details follow file
changes live. See [workflows](workflows.md#settings--agents--workflows).

## Agent Skills

**Agents → CLI & Skills → Agent Skills** lists the user-installable skills bundled in
the app (`Prowl.app/Contents/Resources/skills/`, today `prowl-cli` and `prowl-workflow`) and links them into
your agents' skill folders so every agent reads the version that matches the installed
app. It is the GUI for [`prowl skills`](cli.md#prowl-skills) in user scope and shows the
same status as `prowl skills list`.

- **Rows** — one per bundled `user` skill: name, a short summary (the skill's
  `metadata.prowl-summary`; the agent-facing `description` is shown only when a skill has no
  summary), and **Reveal** (shows the bundled skill folder in Finder). Workflow-only skills are
  not listed.
- **Target lines** — one per *detected* target under each skill: `Claude Code`
  (`~/.claude/skills`), `Codex` (`~/.codex/skills`), `Shared agents directory`
  (`~/.agents/skills`), `Devin` (`~/.config/devin/skills`), `Antigravity`
  (`~/.gemini/antigravity-cli/skills`), and `TraeCode CLI` (`~/.trae/skills`), each
  showing the link's folder
  (`~/.claude/skills/prowl-cli`), its status, and one action. A target is
  detected when its parent folder exists. With no detected target the section
  says so and points at
  `prowl skills install --target <claude|codex|agents|devin|antigravity|trae>`,
  which creates the folder.
- **Statuses and actions** — one explicit action per skill × target link:

  | Status | Meaning | Button |
  |---|---|---|
  | Installed | Symlink → this app's bundled skill | **Remove** (deletes the link only) |
  | Not installed | Nothing in the slot | **Install** (creates the skills folder if needed) |
  | Linked elsewhere `→ path` | Symlink to another Prowl build (for example a Debug build) | **Replace** |
  | Broken link `→ path` | Dangling symlink — the app moved or was removed | **Repair** |
  | Real file or directory | Something that is not a symlink occupies the slot | none — Prowl never deletes it; remove it manually |

- **Aliased targets** — if `~/.claude/skills` and `~/.codex/skills` are symlinks to one
  synced folder, both lines describe the same link: installing or removing through one
  updates the other immediately.
- Results show as a toast; a failure (for example a real directory in the way) also shows
  an alert. Nothing is auto-linked after an update: a newly bundled skill simply appears
  as Not installed. Project-scope links are CLI-only (`prowl skills install --scope project`).
- A Debug build that was not built with `make build-app` has no staged skills; the section
  then reports that the bundled skills are unavailable.

## Archived auto-delete confirmation

When changing the archived auto-delete period, the confirmation lists the worktrees eligible for immediate deletion.
Prowl checks again when you confirm: if another worktree has expired or a repository refresh reveals another eligible
worktree, it updates the warning and asks you to confirm again. The first cleanup uses the accepted targets only;
worktrees unarchived or removed before cleanup are skipped. Later automatic cleanup continues to follow the selected period.

## Gotchas for agents

- Many behaviors are **global with a per-repo override** (copy-files, base
  directory, PR merge strategy, open-with app). A per-repo value of "default"/nil
  means "use the global setting."
- For exact field names, types, and defaults (useful when reading/writing the JSON
  directly), use [`reference/settings-fields.md`](../reference/settings-fields.md).