===============
LIBRARY RULES
===============
From library maintainers:
- Paneflow is a GPU-native terminal multiplexer rendered via GPUI (Zed's Rust UI framework). It is NOT a TUI and NOT an Electron app.
- Configuration lives in paneflow.json under ~/.config/paneflow/. Config keys (default_shell, theme, window_decorations, shortcuts, commands) are English and must never be translated or renamed.
- Keybinding strings use Ctrl/Alt/Shift modifier names verbatim (e.g. Ctrl+Shift+D).
- Paneflow is free and open source under GPL-3.0. There is no paid tier, no login, no telemetry, no backend.
- Paneflow ships for Linux and macOS. Windows is waitlist-only and not shipped yet.
- The live documentation is at https://paneflow.dev/docs. Raw Markdown twins of every docs page are served at the page URL plus .md (e.g. https://paneflow.dev/docs/installation/linux.md).

### Install on Ubuntu/Debian/Mint using APT

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs the .deb package and configures the APT repository for future updates. Ensure you verify the signature before installation.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-<ARCH>.deb
# Verify the signature BEFORE `apt install`: postinst runs as root,
# so an unsigned/tampered .deb could write arbitrary repo sources.
sudo apt install -y dpkg-sig
dpkg-sig --verify paneflow-X.Y.Z-<ARCH>.deb       # expect: GOODSIG
sudo apt install ./paneflow-X.Y.Z-<ARCH>.deb
paneflow --version
```

```bash
sudo apt update && sudo apt upgrade paneflow
```

--------------------------------

### Install PaneFlow on Linux

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Clone the repository, build the application, bundle it into a tarball, and install it to /tmp.

```bash
git clone https://github.com/ArthurDEV44/paneflow.git
cd paneflow
cargo build --release -p paneflow-app
bash scripts/bundle-tarball.sh "$(cargo pkgid -p paneflow-app | sed 's/.*#//')"
tar xzf target/bundle/paneflow-*.tar.gz -C /tmp
/tmp/paneflow.app/install.sh
```

--------------------------------

### Install using Tarball

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs PaneFlow to ~/.local/paneflow.app/ and creates a symlink in ~/.local/bin/paneflow. Suitable for immutable distros or no-root installs.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-<ARCH>.tar.gz
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-<ARCH>.tar.gz.sha256
sha256sum --check paneflow-X.Y.Z-<ARCH>.tar.gz.sha256
tar xzf paneflow-X.Y.Z-<ARCH>.tar.gz
./paneflow.app/install.sh
~/.local/bin/paneflow --version
```

--------------------------------

### Install using AppImage

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Downloads and makes the AppImage executable for portable use on any distribution. No installation or root privileges are required.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-<ARCH>.AppImage
chmod +x paneflow-X.Y.Z-<ARCH>.AppImage
./paneflow-X.Y.Z-<ARCH>.AppImage --version
```

--------------------------------

### Install PaneFlow on macOS

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Install Xcode Command Line Tools, add the target architecture, build the release version, and bundle it into a .app or .dmg.

```bash
# 1. Install Xcode Command Line Tools (one-time)
xcode-select --install

# 2. Add the target
rustup target add aarch64-apple-darwin

# 3. Build
cargo build --release -p paneflow-app --target aarch64-darwin

# 4. Bundle into a .app (produces dist/PaneFlow.app)
bash scripts/bundle-macos.sh \
    --version "$(cargo pkgid -p paneflow-app | sed 's/.*#//')" \
    --arch aarch64

# 5. (Optional) Build a .dmg for local distribution
bash scripts/create-dmg.sh \
    --version "$(cargo pkgid -p paneflow-app | sed 's/.*#//')" \
    --arch aarch64
```

--------------------------------

### Install on Fedora/RHEL/Rocky using DNF

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs the .rpm package and configures the DNF repository for future updates. Import the GPG key and verify the signature before installation.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-<ARCH>.rpm
# Verify the signature BEFORE `dnf install`: %post runs as root.
sudo rpm --import https://pkg.paneflow.dev/gpg      # see Troubleshooting for the TOFU caveat
rpm --checksig paneflow-X.Y.Z-<ARCH>.rpm            # expect: digests signatures OK
sudo dnf install ./paneflow-X.Y.Z-<ARCH>.rpm
paneflow --version
```

```bash
sudo dnf upgrade paneflow
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs the Rust toolchain using rustup. This is required for building Paneflow.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install Fedora System Dependencies

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs essential build libraries for Paneflow on Fedora.

```bash
sudo dnf install gcc pkgconf-pkg-config openssl-devel vulkan-loader-devel \
  wayland-devel libxkbcommon-devel libX11-devel libxcb-devel \
  fontconfig-devel freetype-devel dbus-devel
```

--------------------------------

### Install Debian/Ubuntu System Dependencies

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs essential build libraries for Paneflow on Debian-based systems.

```bash
sudo apt install build-essential pkg-config libssl-dev libvulkan-dev \
  libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev libx11-dev libxcb1-dev \
  libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libfontconfig-dev \
  libfreetype-dev libdbus-1-dev
```

--------------------------------

### Install on macOS (Apple Silicon)

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Downloads the .dmg file for Apple Silicon and opens it for manual installation. A Homebrew cask is also available.

```bash
# Direct download. Drag PaneFlow.app into /Applications from the mounted DMG.
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-X.Y.Z-aarch64-apple-darwin.dmg
open paneflow-X.Y.Z-aarch64-apple-darwin.dmg
```

```bash
brew tap arthurdev44/paneflow
brew install --cask paneflow
```

--------------------------------

### Install PaneFlow on Windows

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Install the Rust MSVC toolchain target, compile the binary, and optionally produce an MSI package using cargo-wix.

```powershell
# 1. Install the Rust MSVC toolchain target (one-time)
rustup target add x86_64-pc-windows-msvc

# 2. Compile the binary
cargo build --release -p paneflow-app --target x86_64-pc-windows-msvc

# 3. (Optional) Produce an MSI via cargo-wix + WiX 3.14
choco install wixtoolset --version 3.14.1
cargo install cargo-wix --version 0.3.9 --locked
cargo wix build --no-build `
    --package paneflow-app `
    --target x86_64-pc-windows-msvc `
    --install-version "$(cargo pkgid -p paneflow-app | ForEach-Object { $_ -replace '.*#','' })"
```

--------------------------------

### Paneflow Configuration File Example

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

This is a comprehensive example of the paneflow.json configuration file, showing various settings for shell, theme, font, window decorations, AI agent buttons, telemetry, and commands.

```json
{
  "$schema": "https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json",
  "$schemaVersion": "1.0.0",
  "default_shell": "/bin/zsh",
  "theme": "One Dark",
  "font_family": ".PaneflowMono",
  "font_size": 14,
  "line_height": 1.3,
  "window_decorations": "client",
  "option_as_meta": true,
  "shortcuts": {},
  "terminal": {
    "ligatures": false
  },
  "telemetry": {
    "enabled": null
  },
  "claude_code_button_visible": true,
  "claude_code_bypass_permissions": false,
  "codex_button_visible": true,
  "opencode_button_visible": true,
  "pi_button_visible": true,
  "hermes_agent_button_visible": true,
  "commands": []
}
```

--------------------------------

### Complete PaneFlow Configuration Example

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/configuration/schema.md

A comprehensive example demonstrating various configuration options for PaneFlow, including shell, theme, fonts, window decorations, input handling, terminal settings, telemetry, and AI agent buttons.

```json
{
  "$schema": "https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json",
  "default_shell": "/bin/zsh",
  "theme": "One Dark",
  "font_family": "JetBrains Mono",
  "font_size": 14,
  "line_height": 1.3,
  "window_decorations": "client",
  "option_as_meta": true,
  "shortcuts": {},
  "terminal": { "ligatures": false, "scrollback_lines": 10000 },
  "telemetry": { "enabled": null },
  "claude_code_button_visible": true,
  "claude_code_bypass_permissions": false,
  "codex_button_visible": true,
  "opencode_button_visible": true,
  "commands": []
}
```

--------------------------------

### Install Paneflow on Ubuntu/Debian (x86_64)

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Download the .deb package for x86_64 architecture and install it using apt. This method automatically handles system dependencies.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/download/v0.2.17/paneflow-0.2.17-x86_64.deb
sudo apt install ./paneflow-0.2.17-x86_64.deb
```

--------------------------------

### Install Arch Linux System Dependencies

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs essential build libraries for Paneflow on Arch Linux.

```bash
sudo pacman -S base-devel pkg-config openssl vulkan-icd-loader wayland \
  libxkbcommon libx11 libxcb fontconfig freetype2 dbus
```

--------------------------------

### Install WSL2 and Ubuntu on Windows

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/windows.md

Enable WSL2 and install the default Ubuntu distribution. This command requires administrative privileges in PowerShell.

```powershell
wsl --install
```

--------------------------------

### Install Vulkan GPU Drivers (Linux)

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs Vulkan drivers for AMD/Intel (Mesa) and NVIDIA GPUs on Linux. Also includes a command to verify Vulkan installation.

```bash
# AMD/Intel (Mesa)
sudo apt install mesa-vulkan-drivers        # Debian/Ubuntu
sudo dnf install mesa-vulkan-drivers        # Fedora
sudo pacman -S vulkan-radeon vulkan-intel    # Arch

# NVIDIA
sudo apt install nvidia-vulkan-icd          # Debian/Ubuntu
sudo pacman -S nvidia-utils                 # Arch

# Verify Vulkan works
vulkaninfo --summary
```

--------------------------------

### Install Paneflow on Ubuntu/Debian (ARM64)

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Download the .deb package for ARM64 architecture (e.g., Raspberry Pi 5) and install it using apt. This method automatically handles system dependencies.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/download/v0.2.17/paneflow-0.2.17-aarch64.deb
sudo apt install ./paneflow-0.2.17-aarch64.deb
```

--------------------------------

### Install Persistent Hooks

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/hooks.md

Installs persistent hooks for all supported agents. This command writes to `~/.claude/settings.json`.

```bash
paneflow hooks setup
```

--------------------------------

### Install Vulkan Drivers on Fedora

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/troubleshooting.md

Install the necessary Vulkan libraries and drivers on Fedora systems to resolve GPU-related launch errors.

```bash
sudo dnf install vulkan-loader mesa-vulkan-drivers
```

--------------------------------

### Verify Paneflow Installation

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Run 'paneflow --version' to confirm the installation and check if the binary is accessible in your PATH. The expected output is 'paneflow 0.2.x'.

```text
paneflow --version
```

```text
paneflow 0.2.x
```

--------------------------------

### Install Paneflow from Tarball

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Download the tarball, extract it, and move the 'paneflow' binary to a directory in your PATH, such as ~/.local/bin. This method offers manual control over binary placement.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/download/v0.2.17/paneflow-0.2.17-x86_64.tar.gz
tar -xzf paneflow-0.2.17-x86_64.tar.gz
mkdir -p ~/.local/bin
mv paneflow ~/.local/bin/
chmod +x ~/.local/bin/paneflow
```

--------------------------------

### Verify Paneflow Installation via CLI

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/macos.md

Check the installed Paneflow version by running the command after it has been added to the system's PATH.

```bash
paneflow --version
```

--------------------------------

### Resolve Latest Version and Architecture

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Automatically fetches the latest release version tag and the system's architecture. Replace placeholders in installation commands with these values.

```bash
VER=$(curl -fsSL https://api.github.com/repos/ArthurDEV44/paneflow/releases/latest \
      | grep -oE '"tag_name":\s*"v[^" ]+"' | cut -d\" -f4 | sed 's/^v//')
ARCH=$(uname -m)
```

--------------------------------

### Install Paneflow as AppImage

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Download the AppImage, make it executable, and run it directly. This method requires no root privileges or package manager and works on most modern Linux distributions.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/download/v0.2.17/paneflow-0.2.17-x86_64.AppImage
chmod +x paneflow-0.2.17-x86_64.AppImage
./paneflow-0.2.17-x86_64.AppImage
```

--------------------------------

### Example flow.toml Configuration

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

This TOML defines a review pipeline with two steps: 'impl' for implementation and 'review' for summarization. The 'impl' step runs a command in a specific directory and captures output, while the 'review' step sends a summary to the 'impl' step.

```toml
name = "review-pipeline"
layout = "even_h"

[defaults]
timeout_secs = 600

[[step]]
id = "impl"
pane = { cwd = "~/dev/api", agent = "claude", prompt = "implement the fix and run the tests" }
submit = true
ready = { pattern = "tests? passed" }
capture = { var = "summary", lines = 20 }

[[step]]
id = "review"
needs = ["impl"]
send = { target = "impl", text = "Summarise what changed:\n${summary}" }
```

--------------------------------

### Install Vulkan Drivers on Arch Linux

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/troubleshooting.md

Install the necessary Vulkan libraries and drivers on Arch Linux systems to resolve GPU-related launch errors.

```bash
sudo pacman -S vulkan-icd-loader mesa
```

--------------------------------

### Install Vulkan Drivers on Debian/Ubuntu

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/troubleshooting.md

Install the necessary Vulkan libraries and drivers on Debian or Ubuntu systems to resolve GPU-related launch errors.

```bash
sudo apt install libvulkan1 mesa-vulkan-drivers
```

--------------------------------

### Install MCP Bridge

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Installs the Paneflow MCP bridge for agent communication. This command detects agents and writes configuration entries.

```bash
paneflow mcp install
```

--------------------------------

### Setup Lifecycle Hooks

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Sets up persistent, user-scope lifecycle hooks for Paneflow, primarily for Claude Code.

```bash
paneflow hooks setup
```

--------------------------------

### Install Paneflow MCP Bridge

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/mcp-bridge.md

Registers the paneflow-mcp bridge with installed CLI agents. This command is idempotent and no-clobber.

```bash
paneflow mcp install
```

--------------------------------

### Paneflow Shortcut Override Example

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/troubleshooting.md

Example of how to override default shortcuts in Paneflow's configuration file. Ensure action names are in snake_case and keystrokes are lowercase and plus-separated.

```json
{
  "shortcuts": {
    "ctrl+shift+t": "new_tab"
  }
}
```

--------------------------------

### Install Paneflow Linux .deb package in WSL2

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/windows.md

Download the latest Paneflow .deb package and install it using apt within your WSL2 distribution. This allows you to run Paneflow through WSLg.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-x86_64.deb

```

```bash
sudo apt install ./paneflow-x86_64.deb
```

```bash
paneflow
```

--------------------------------

### Configuration Schema Reference

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

An example showing how to reference the Paneflow configuration schema within your paneflow.json file. This enables editor-side autocomplete and validation.

```json
{
  "$schema": "https://github.com/ArthurDEV44/paneflow/raw/main/schemas/paneflow.schema.json",
  "$schemaVersion": "1.0.0"
}
```

--------------------------------

### List Workspaces via Paneflow IPC

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Example of how to request a list of available workspaces from Paneflow via its IPC endpoint using socat and a Unix socket.

```bash
# List workspaces
 echo '{"jsonrpc":"2.0","method":"workspace.list","id":1}' \
  | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/paneflow/paneflow.sock
```

--------------------------------

### Example Paneflow Workspace Configuration

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Defines a workspace named 'feat-x' with a vertical main layout and two panes. The first pane is focused and uses the 'claude' agent with a specific prompt. The second pane runs a 'cargo watch' command for tests.

```toml
name = "feat-x"
layout = "main_vertical"

[[panes]]
cwd = "~/dev/api"
agent = "claude"
prompt = "review the diff on this branch"
focus = true

[[panes]]
cwd = "~/dev/api"
command = "cargo watch -x test"
name = "tests"
```

--------------------------------

### Install Paneflow on Linux

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

This script downloads the latest AppImage release of Paneflow for Linux, makes it executable, and runs it. It automatically detects the system architecture and fetches the latest version tag.

```bash
# Linux portable AppImage
VER=$(curl -fsSL https://api.github.com/repos/ArthurDEV44/paneflow/releases/latest \
      | grep -oE '"tag_name":\s*"v[^" ]+"' | cut -d\" -f4 | sed 's/^v//')
ARCH=$(uname -m)
curl -LO "https://github.com/ArthurDEV44/paneflow/releases/latest/download/paneflow-${VER}-${ARCH}.AppImage"
chmod +x "paneflow-${VER}-${ARCH}.AppImage"
./paneflow-${VER}-${ARCH}.AppImage
```

--------------------------------

### Run AppImage with extract-and-run fallback

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

If the AppImage fails to mount due to missing FUSE 2, use this command to extract and run it. Alternatively, install libfuse2t64.

```bash
./paneflow-0.2.17-x86_64.AppImage --appimage-extract-and-run
```

--------------------------------

### Install FUSE Compatibility Shim on Ubuntu

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs the `libfuse2` compatibility package on Ubuntu systems to allow AppImages to run using FUSE. Note the package name difference between Ubuntu 22.04 and 24.04.

```bash
sudo apt install libfuse2t64
# On Ubuntu 22.04 the package is `libfuse2` instead.
```

--------------------------------

### workspace.current

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Gets information about the currently active workspace.

```APIDOC
## workspace.current

### Description
Returns details about the currently active workspace.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
None

### Returns
Information about the active workspace.
```

--------------------------------

### Get System Capabilities via JSON-RPC

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

This bash command queries the Paneflow socket for system capabilities, including the live state of the scripting gate. It's useful for understanding the server's current status and available features.

```bash
printf '%s\n' '{"jsonrpc":"2.0","method":"system.capabilities","params":{},"id":1}' \
  | nc -U "$PANEFLOW_SOCKET_PATH"
```

--------------------------------

### List Panes

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Displays a human-readable list of all active panes. Useful for getting an overview of the current workspace.

```bash
# What is running right now?
paneflow ls --human
```

--------------------------------

### Start an AI Agent in Paneflow

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/index.md

Initiate an AI agent within a new Paneflow pane. Paneflow supports various agents like Claude Code, Codex, and OpenCode, running them as first-class panes.

```bash
claude     # Anthropic's Claude Code
```

```bash
codex      # OpenAI's Codex CLI
```

```bash
opencode   # OpenCode
```

--------------------------------

### Troubleshoot 'No GPU adapter found' with Software ICD

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Installs a software Vulkan ICD (lavapipe) for headless or GPU-less environments like WSL2. This command forces the use of the software ICD.

```bash
# Install a Vulkan ICD (see Prerequisites > Vulkan GPU driver above).
vulkaninfo --summary    # should list at least one physicalDevice

# WSL2 / headless / GPU-less hosts: force the lavapipe software ICD.
sudo apt install mesa-vulkan-drivers  # Debian/Ubuntu
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.x86_64.json paneflow
```

--------------------------------

### Override Paneflow Keybindings

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/keybindings.md

Example of how to override default Paneflow keybindings by defining custom shortcuts in the `paneflow.json` file. This demonstrates mapping keystrokes to specific actions.

```json
{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "alt+1": "select_workspace_1"
  }
}
```

--------------------------------

### Run AppImage without FUSE on Ubuntu 24.04+

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Executes an AppImage by extracting and running it in-process, avoiding the need for the FUSE library which is not installed by default on Ubuntu 24.04 and newer.

```bash
./paneflow-X.Y.Z-x86_64.AppImage --appimage-extract-and-run
```

--------------------------------

### Create and Manage Workspace Panes

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Demonstrates creating new panes, splitting existing ones, and focusing on specific panes based on their target or working directory. Useful for setting up complex development environments.

```bash
# Workspace with two panes, focus the editor side
paneflow new --name api --cwd ~/dev/api
paneflow split v --target api
paneflow focus cwd:~/dev/api
```

--------------------------------

### Basic PaneFlow Usage

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Launch the application, enable logging, or display version and help information.

```bash
# Launch
paneflow

# With logging
RUST_LOG=info paneflow

# Print version / help
paneflow --version
paneflow --help

# CI self-update harness (exit codes 0-5)
paneflow --update-and-exit
```

--------------------------------

### Uninstall Paneflow (AppImage)

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Removes an AppImage installation of Paneflow. No other files are installed, so simply deleting the AppImage file is sufficient.

```bash
rm paneflow-X.Y.Z-<ARCH>.AppImage
```

--------------------------------

### workspace.up

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Declaratively spawns a workspace with a given name, layout, and panes.

```APIDOC
## workspace.up

### Description
Declaratively spawns a workspace. This method is used by `paneflow up`/`flow` commands. It takes a name, layout, and an array of panes.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
#### Request Body
- **name** (string) - Required - The name of the workspace.
- **layout** (object) - Required - The layout tree for the workspace.
- **panes** (array) - Required - An array of pane configurations.

### Returns
An object containing the `index`, `title`, `panes`, and `surface_ids` of the spawned workspace.
```

--------------------------------

### Launch Paneflow Application

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/macos.md

Open the Paneflow application from the Applications folder using the 'open' command.

```bash
open /Applications/Paneflow.app
```

--------------------------------

### Running a Multi-Agent Pipeline with flow.toml

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Shows how to execute a declarative DAG using `paneflow flow run <file>`, detailing the commands for spawning steps, waiting on barriers, and sending data between panes.

```toml
# paneflow flow run <file>
```

--------------------------------

### Download and Open Paneflow DMG

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/macos.md

Use curl to download the latest Apple Silicon .dmg file and then open it to mount the disk image.

```bash
curl -LO https://github.com/ArthurDEV44/paneflow/releases/download/v0.2.17/paneflow-0.2.17-aarch64-apple-darwin.dmg
open paneflow-0.2.17-aarch64-apple-darwin.dmg
```

--------------------------------

### workspace.create

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Creates a new workspace with optional name, current working directory, and layout.

```APIDOC
## workspace.create

### Description
Creates a new workspace. The `cwd` will be canonicalized and must be a directory. An optional layout tree can be provided.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **name** (string) - Optional - The name for the new workspace.
- **cwd** (string) - Optional - The current working directory for the workspace.
- **layout** (object) - Optional - The layout tree for the workspace.

### Returns
Information about the created workspace, including the canonicalized `cwd`.
```

--------------------------------

### Check Hook Status

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/hooks.md

Reports the installation status of hooks for each agent. Useful for verifying configurations.

```bash
paneflow hooks status
```

--------------------------------

### Handle Unsigned Dev Build First Launch on macOS

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Strip the quarantine attribute from an unsigned application bundle to bypass macOS Gatekeeper restrictions.

```bash
xattr -cr dist/PaneFlow.app
open dist/PaneFlow.app
```

--------------------------------

### Check Paneflow MCP Bridge Status

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/mcp-bridge.md

Reports the installation state of the paneflow-mcp bridge for each agent.

```bash
paneflow mcp status
```

--------------------------------

### surface.list

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Lists all available surfaces, including their IDs, names, titles, current working directories, commands, and associated workspaces.

```APIDOC
## surface.list

### Description
Retrieves a list of all available surfaces. Each surface object includes its ID, name, title, current working directory, command, and the workspace it belongs to.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
None

### Returns
An object containing a `surfaces` array, where each element is a surface object with `surface_id`, `name`, `title`, `cwd`, `cmd`, and `workspace`.
```

--------------------------------

### Port Offset Allocation Explanation

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Explains how the `${port_offset}` variable is used to allocate isolated ports for each pane, starting from `port_base`.

```markdown
`${port_offset}` gives each pane that references it an isolated port:
allocation starts at `port_base` and probes in strides of 10
(pane 0 → 3000, next → 3010, skipping ports that are already bound).
It substitutes **only inside `env` values**; any other `${…}` token in
the spec is a validation error. Orphaned worktrees are pruned at the
next Paneflow startup.

The whole spec fails atomically: every `cwd` is canonicalised before
any pane is created, so a typo never leaves a half-built workspace.
```

--------------------------------

### Codex CLI Configuration

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/mcp-bridge.md

Configure the MCP bridge for Codex by specifying the command and arguments in ~/.codex/config.toml. This setup assumes the bridge is treated as a tool.

```toml
[mcp_servers.paneflow]
command = "/absolute/path/to/paneflow-mcp"
args = []

```

--------------------------------

### Uninstall Paneflow (.tar.gz)

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Removes Paneflow files installed from a .tar.gz archive, including application files, binaries, desktop entries, and optionally configuration and cache.

```bash
rm -rf ~/.local/paneflow.app ~/.local/bin/paneflow \
       ~/.local/share/applications/paneflow.desktop
for s in 16 32 48 128 256 512; do
    rm -f ~/.local/share/icons/hicolor/${s}x${s}/apps/paneflow.png
done
# Optional: remove config and cache
rm -rf ~/.config/paneflow ~/.cache/paneflow
```

--------------------------------

### Add AppImage to PATH

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/linux.md

Move the downloaded AppImage to ~/.local/bin and rename it to 'paneflow' for easy access from anywhere in the terminal. Ensure the directory is in your PATH.

```bash
mkdir -p ~/.local/bin
mv paneflow-0.2.17-x86_64.AppImage ~/.local/bin/paneflow
chmod +x ~/.local/bin/paneflow
```

--------------------------------

### Tiled Layout Visualization

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/layouts.md

Illustrates how panes are arranged in a balanced grid for 4 and 6 panes using the tiled layout.

```text
4 panes              6 panes
+--------+--------+  +------+------+------+
|   1    |   2    |  |  1   |  2   |  3   |
|        |        |  |      |      |      |
+--------+--------+  +------+------+------+
|   3    |   4    |  |  4   |  5   |  6   |
|        |        |  |      |      |      |
+--------+--------+  +------+------+------+
```

--------------------------------

### Set Font Family

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/configuration/schema.md

Configure the font family for Paneflow. The resolution process includes alias expansion, embedded font checks, and validation against installed monospace fonts.

```json
{ "font_family": "JetBrains Mono" }
```

--------------------------------

### Launch Paneflow Application via Alias

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/macos.md

An alternative method to launch the Paneflow application using the '-a' flag with the 'open' command.

```bash
open -a Paneflow
```

--------------------------------

### Run Paneflow

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/index.md

Launch Paneflow from your terminal. The application opens with a single workspace and shell pane, named after the current directory.

```bash
paneflow
```

--------------------------------

### Ping Paneflow IPC Endpoint

Source: https://github.com/arthurdev44/paneflow/blob/main/README.md

Example of how to send a 'ping' request to the Paneflow IPC endpoint using socat and a Unix socket. This is useful for checking if Paneflow is running and responsive.

```bash
# Ping
 echo '{"jsonrpc":"2.0","method":"system.ping","id":1}' \
  | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/paneflow/paneflow.sock
```

--------------------------------

### ai.session_start, ai.prompt_submit, ai.tool_use, ai.notification, ai.stop, ai.session_end

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Lifecycle telemetry events from `paneflow-ai-hook`. These are read-only on the UI side.

```APIDOC
## AI Telemetry Hooks

### Description
These methods represent lifecycle telemetry events from `paneflow-ai-hook`. They are read-only on the UI side and are used for tracking AI session activity.

### Methods
- `ai.session_start`
- `ai.prompt_submit`
- `ai.tool_use`
- `ai.notification`
- `ai.stop`
- `ai.session_end`

### Parameters
- **hook payloads** (object) - Required - The specific payload structure depends on the method called.

### Response
#### Success Response (200)
Details of the success response are not specified as these are telemetry events.

#### Response Example
Details of the response example are not specified.
```

--------------------------------

### workspace.list

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Lists all available workspaces, including their indexes and titles.

```APIDOC
## workspace.list

### Description
Retrieves a list of all available workspaces, showing their index and title.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
None

### Returns
A list of workspaces, each with an `index` and `title`.
```

--------------------------------

### system.capabilities

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Discovers the capabilities of the PaneFlow agent, including scripting support and available methods.

```APIDOC
## system.capabilities

### Description
Retrieves the capabilities of the PaneFlow agent, such as whether scripting is enabled and a list of available methods.

### Method
N/A (Internal API Call)

### Endpoint
N/A

### Parameters
None

### Returns
An object containing `scripting` (boolean) and `methods` (array of strings).
```

--------------------------------

### Send Text and Wait for Pattern

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/scripting.md

Shows how to send text to a pane for review and then wait for a specific pattern to appear in its output. Requires the scripting gate to be enabled (`PANEFLOW_IPC_SCRIPTING=1`).

```bash
# Stage a command for the user to review (no submit), then watch
PANEFLOW_IPC_SCRIPTING=1  # must be set on the Paneflow process itself
paneflow send backend "cargo test --workspace"
paneflow wait --match backend --pattern "test result" --timeout 120
```

--------------------------------

### Gemini CLI Configuration

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/mcp-bridge.md

Set up the MCP bridge for Gemini in ~/.gemini/settings.json. The 'trust' option can be set to true to bypass confirmation prompts for local binaries.

```json
{
  "mcpServers": {
    "paneflow": {
      "command": "/absolute/path/to/paneflow-mcp",
      "args": [],
      "trust": true
    }
  }
}

```

--------------------------------

### Symlink Paneflow Binary to PATH

Source: https://github.com/arthurdev44/paneflow/blob/main/docs/user/installation/macos.md

Create a symbolic link to make the Paneflow CLI accessible from any terminal location. This requires administrator privileges.

```bash
sudo ln -sf /Applications/Paneflow.app/Contents/MacOS/paneflow /usr/local/bin/paneflow
```