Prowl Manual
Every view, panel, workflow, shortcut and CLI command, straight from the Prowl repository. These are the same Markdown files that ship inside the app, so what you read here is what your agent reads.
Layout & navigation
- View Modes — Normal / Canvas / Shelf The same open worktrees, three layouts. Switching modes rearranges the view; it never changes your running sessions.
- Canvas View A zoomable board where every agent is a live, interactive terminal card — watch them all at once, and broadcast one command to every selected agent.
- Shelf View Worktrees as vertical "book spines" stacked on the side — flip through your whole stack from the keyboard, never losing your place.
- Repositories & Git Worktrees The sidebar and everything in it: adding projects, and creating, opening, archiving, and deleting git worktrees — the unit of work you hand to an agent.
- Workspaces
- Terminal — Tabs, Splits & Panes The terminal layer: tabs within a worktree, splitting a tab into panes, the Ghostty engine underneath, tab titles & icons, shell integration, and fonts.
- Command Palette The ⌘P searchable launcher for (almost) every action in Prowl. Type a name, hit Return.
Agents
- Active Agents Panel A live list of every running agent across all worktrees, with status and one-click jump-to-agent. Your mission-control roster.
- Agent Island An opt-in, notch-aware projection of Active Agents at the top of one display.
- Agent Profiles Named launch presets for every agent runtime Prowl recognizes: one click in the toolbar Agents menu or the Command Palette starts a fresh agent in the current worktree with your model, effort, mode, and — optionally — a dedicated account.
- Agent Detection How Prowl knows there's an agent in a pane and whether it's Working, Blocked, Idle, or Done — and which agents it recognizes.
- Notifications & Agent Reminders How Prowl tells you an agent finished or needs you — system notifications, the bell/unread indicators, and Dock badge/bounce.
Automation
- 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.
- Agent Workflows Multi-step, multi-agent orchestrations that Prowl runs and supervises for you: a workflow bundle declares the roles (the pane you start from, an agent Prowl launches, an agent you pick) and the steps (message a role, launch one, loop until a verdict, notify, close); Prowl types the instructions into the right panes, waits for each delivery, and shows the run in the toolbar. This page covers the feature end to end — files, entry points, the start sheet, the run panel, and Settings → Agents → Workflows. For the CLI commands and their JSON, see cli.md; to write or debug a workflow, an agent should load the bundled prowl-workflow skill.
- Handoff — Workflow Use the built-in prowl.handoff workflow to collect an agent-authored briefing, preserve durable context under .prowl/handoff/, and optionally launch a receiver.
- The prowl CLI A command-line interface to inspect and drive the running Prowl app — so you (or an agent) can list panes, read their screens, run commands and capture output, send keystrokes, focus, and open/close tabs and panes programmatically.
Or let your agent read it for you
Hand this prompt to Claude Code, Codex, or any assistant. It fetches this manual from the repository and introduces Prowl in your language, tailored to how you work. Inside the app, Help → Ask Agent About Prowl copies the same prompt pointed at the bundled docs.
Read Prowl's documentation and introduce it to me. Prowl is a native macOS command center for running many AI coding agents in parallel. Its full manual lives here: https://raw.githubusercontent.com/onevcat/Prowl/refs/heads/main/docs/README.md Fetch that index and read it (it links to an overview and per-feature manuals in the same docs/ folder — read the relevant ones). Then: 1. Briefly tell me what Prowl is and why it's worth my time. 2. Based on what you know about how I work, suggest 3–4 Prowl features that would genuinely help me, each with a one-line "how". 3. Then answer my follow-up questions, consulting the matching doc. Reply in my preferred language.
Prowl Documentation — Index
Prowl is a native macOS command center for running multiple AI coding agents (Claude Code, Codex, Gemini, Cursor, and friends) in parallel — each in its own terminal, tab, split, and git worktree. This documentation set is the operator’s manual for the app.
Who this is for#
The primary reader of these docs is an AI agent, not a human. A human will usually point their agent at this folder and then ask questions like “how do I broadcast a command to every agent at once?” or “what does the Shelf view do?”. The agent reads the relevant file(s) here and answers precisely, then the human drills into whatever interests them.
Everything here is plain Markdown — no images required. It is written to be searched by filename and keyword, read in full quickly, and quoted accurately.
How to use this documentation (for agents)#
- Start here. This index maps every feature to a file.
- For a pitch / first impression, read
overview.md— the “most exciting” features, suitable for introducing Prowl to a human. - For the mental model, read
concepts.md— the repository → worktree → tab → pane hierarchy, view modes, and glossary. Read this before answering anything structural. - For a specific feature, open the matching file in
components/. Each is a self-contained manual for one part of the app. - For exact lookups (every keyboard shortcut, every setting field), use
reference/. - To actually drive the app programmatically, read
components/cli.md— theprowlcommand-line interface.
Filenames are descriptive on purpose. A keyword search such as
grep -ri "broadcast" docs/ or grep -ri "worktree" docs/ will land on the
right file.
Component manuals#
Each file under components/ documents one part: what it is, how to open it,
its keyboard shortcuts, detailed behavior, settings, and gotchas.
| File | What it covers |
|---|---|
components/repositories-and-worktrees.md | The sidebar: adding repositories, creating / opening / archiving / deleting git worktrees, plain (non-git) folders, pinning, ordering, repository icons & colors. |
components/workspaces.md | Multi-repo workspaces: one agent terminal rooted at a shared folder, with .prowl/workspace.json metadata describing the repositories in scope. |
components/terminal.md | Terminal tabs, splits/panes, surfaces, the Ghostty engine, tab titles & icons, shell integration, scrollback, font size. |
components/canvas.md | Canvas view — a zoomable board of live terminal cards, multi-select, and broadcast a command to every agent at once. |
components/shelf.md | Shelf view — worktrees as vertical “book spines” you flip through from the keyboard. |
components/view-modes.md | Switching between Normal / Canvas / Shelf layouts and what each is good for. |
components/command-palette.md | ⌘P searchable command launcher; every action category it exposes. |
components/active-agents.md | The Active Agents panel: a live list of every running agent and its status, with one-click jump-to-agent. |
components/agent-island.md | A notch-aware Active Agents projection with state counts, Blocked/Done callouts, and full roster. |
components/agent-detection.md | How Prowl knows an agent is Working / Blocked / Idle / Done, which agents it recognizes, and how the status indicator works. |
components/agent-profiles.md | Agent Profiles: named launch presets for Claude Code/Codex (model, effort, mode, placement), the Agents launcher menu, recommended-profile resolution, and opt-in dedicated homes for separate accounts. |
components/notifications.md | Agent-finished reminders, command-finished notifications, the bell/unread indicators, and Dock badge/bounce. |
components/diff-view.md | Show Diff (⌘⇧Y) for working-tree changes vs HEAD, plus Outgoing Changes for pull-request branch diffs. |
components/github-pull-requests.md | GitHub PR integration via gh: PR status, CI checks, merge/close/re-run actions from the command palette. |
components/custom-actions.md | Run Script (⌘R/⌘.), Setup & Archive scripts, and per-repo Custom Commands with their own buttons & hotkeys. Injected env vars. |
components/settings.md | The Settings window (⌘,): every tab and what it controls. |
components/updates.md | Sparkle auto-updates: auto-check, ⌘⇧U. |
components/cli.md | The prowl CLI — let an agent inspect and drive panes (list, agents, profiles, skills, workflow, focus, send, key, read, create, close, open). |
components/workflows.md | Agent Workflows: .pwlworkflow bundles with agent steps, script actions, typed state and control flow — approval, the start sheet, the run panel, and Settings → Agents → Workflows. |
components/handoff.md | Hand a task off between agents with the prowl.handoff workflow and durable .prowl/handoff/ packets. |
Reference (exact lookups)#
| File | What it covers |
|---|---|
reference/keyboard-shortcuts.md | The complete, authoritative keyboard-shortcut table, grouped by category, with command IDs and remappability. |
reference/settings-fields.md | Every GlobalSettings and per-repository setting field: name, type, default, effect, and on-disk location. |
Find by task (reverse lookup)#
| I want to… | Read |
|---|---|
| Run many agents side by side and see them all | components/canvas.md, components/shelf.md |
| Give one agent a task that spans several repos | components/workspaces.md |
| Hand a task off between agents | components/handoff.md |
| Run a multi-agent workflow (e.g. launch a reviewer and loop until clean) | components/workflows.md |
| Send one command to every agent simultaneously | components/canvas.md (broadcast) |
| Spin up a new branch/worktree for a new agent | components/repositories-and-worktrees.md |
| Find / run any action by name | components/command-palette.md |
| See which agents are working vs waiting on me | components/active-agents.md, components/agent-detection.md |
| Get notified when an agent finishes | components/notifications.md |
Bind swift build / npm test to a button + hotkey | components/custom-actions.md |
| Review what an agent changed | components/diff-view.md |
| Open / merge / re-run CI on a pull request | components/github-pull-requests.md |
| Drive a pane from a script or another agent | components/cli.md |
| Look up a keyboard shortcut | reference/keyboard-shortcuts.md |
| Change app behavior / a setting | components/settings.md, reference/settings-fields.md |
Conventions used in these docs#
- Modifier symbols: ⌘ Command · ⇧ Shift · ⌥ Option · ⌃ Control · ↩ Return · ⌫ Delete (Backspace).
- Default shortcuts are shown. Most app shortcuts are user-remappable in
Settings → Shortcuts, so a human’s actual keys may differ — when in doubt,
the Command Palette shows the live binding
next to each action, and the
prowlCLI never depends on keybindings. - Requirements: macOS 26.0+.
- Website: https://prowl.onev.cat · Source: https://github.com/onevcat/Prowl