index.md

PaneFlow (macOS-only fork)

Internal docs for The AAM Group's private macOS-only fork of PaneFlow. Not for publication.

PaneFlow is a native, GPU-accelerated terminal workspace built for agentic CLI workflows: Claude Code, Codex, OpenCode, and any other agent that speaks plain shell. Split panes, persistent sessions, dev-server port detection, and bundled themes.

This fork drops Windows and Linux support entirely. There is no public download, no Homebrew tap, and no public issue tracker. Build it from source: see INSTALL.md.

Contents

Getting it running

• INSTALL.md - build from source, including the Metal toolchain step that is easy to miss.
• installation/macos - .app bundle, PATH symlink, Gatekeeper.
• troubleshooting - symptom-first fixes.

Using it

• features - the capability tour.
• keybindings - default shortcuts and overrides.
• layouts - the four layout presets.
• review - the Diff view and agent review.
• themes - the bundled themes.

Configuring it

• installation - where the config file lives for debug vs release.
• settings - the Settings panel and what it writes.
• configuration - how paneflow.json is read.
• configuration/schema - every recognised key, type, and default.

Automating it

• scripting - CLI, JSON-RPC, events, workspace and flow files, MCP, hooks.
• scripting/reference - the exact surface to quote.
• conductor - driving agent panes from the CLI. Read the status note first: this is known-unreliable.
• conductor/reference - conductor verbs, fields, and events.

What runs on the inside

• Pure Rust + GPUI, the same framework Zed runs on. Rendering goes through Metal.
• Native VT emulation via a vendored libghostty-vt static archive (upstream Ghostty f2d5758f, tag v0.10.0), wrapped by the paneflow-terminal-ghostty crate. It is the only engine - no fallback, no feature flag, no terminal.backend key. PaneFlow owns the PTY itself through portable-pty; libghostty parses the bytes and owns the grid; GPUI paints the snapshots. The archive is checked in under native/libghostty/prebuilt/aarch64-apple-darwin/ and hash-verified at build time, so no Zig toolchain is needed to build PaneFlow.
• JSON-RPC IPC over a Unix domain socket under the user runtime directory. See scripting/reference.
• Latency probes for cold start, keystroke-to-pixel, and pixel-coordinate tracing. Debug builds only (#[cfg(debug_assertions)]), opt in with PANEFLOW_LATENCY_PROBE=1 or PANEFLOW_PIXEL_PROBE=1.

System requirements

Requirement	Value
OS	macOS 13 Ventura or later (LSMinimumSystemVersion in assets/Info.plist)
Architecture	Apple Silicon. There is no x86_64-apple-darwin build.
GPU	Metal, built in

Licence

GPL-3.0-or-later. GPUI is a Zed fork, so the licence is mandatory, not a choice. See LICENSE.

Fork context

Fork rationale, staged cut plan, verified traps, and the running defect list live in docs/fork/2026-08-25-mac-only-fork-design.md.